| At line 1 added one line |
| \\ |
| At line 4 added 4 lines |
| ---- |
| __⚠️ Proxy Configuration:__ if your server accesses the internet through a proxy, ensure that the following Let’s Encrypt domains are whitelisted to allow successful certificate issuance and renewal:\\ |
| - __acme-v02.api.letsencrypt.org__\\ |
| - __acme-staging-v02.api.letsencrypt.org__\\ |
| At line 4 changed 4 lines |
| ***\\ |
| About : __''DST Root CA X3 Expiration (September 2021)''__ See oficial description : https://letsencrypt.org/docs/dst-root-ca-x3-expiration-september-2021/\\ |
| If your root cert is still __DST Root CA__ => Make sure that flags "__Delete account key pair__" and " __Delete domain key pair__" are checked and renew your certificate. After the renew the new root certificate will be: __ISRG Root X1__. |
| ***\\ |
| ---- |
| At line 11 added one line |
| __About Let’s Encrypt__: Let’s Encrypt is a free, automated, and open certificate authority (CA) that issues domain-validated (DV) TLS/SSL certificates to help secure websites and services. Learn more at [Let’s Encrypt Link|https://letsencrypt.org/how-it-works].\\ |
| At line 10 changed one line |
| About Let's Encrypt: It is a certificate authority that provides certificates (only domain-validated certificates) for free. (for more info : [https://letsencrypt.org/how-it-works/])\\ |
| The Let’s Encrypt plugin in CrushFTP simplifies certificate management by automatically generating a __Java Keystore (.jks)__ file containing a valid certificate from Let’s Encrypt. This plugin eliminates the need to install or configure external tools like Certbot — everything is handled directly within CrushFTP.\\ |
| At line 15 added 2 lines |
| [attachments|lets_encrypt_header.png]\\ |
| [attachments|lets_encrypt.png]\\ |
| At line 13 changed one line |
| LetsEncrypt plugin allows you to create a java key store file (the .JKS file) authorized by the Let's Encrypt certificate authority. You do not need to install, configure, or do anything with certbot if using this plugin.\\ |
| ✅ __Enabled__: Turns the Let’s Encrypt plugin on so it runs and attempts to manage certificates.\\ |
| At line 15 changed 2 lines |
| [attachments|lets_encrypt_header.png] |
| [attachments|lets_encrypt.png]\\ |
| ✅ __Debug__: Enables verbose logging to help diagnose issues during certificate generation or renewal.\\ |
| At line 18 changed one line |
| Server Instance : To generate certificate for DMZ just specify the DMZ server instance name. The Let's encrypt server will test the given server instance. Leave it empty for normal case. \\ |
| __ACME Host__: acme-v02.api.letsencrypt.org: The production Let’s Encrypt ACME server for issuing real certificates.\\ |
| __ACME Staging Host__: acme-staging-v02.api.letsencrypt.org: Used for testing — issues dummy certs that aren’t trusted by browsers but avoid hitting rate limits.\\ |
| \\ |
| __Server Instance__: Selects which CrushFTP server instance ([DMZ] node) the certificate should be generated for. Let’s Encrypt will challenge that server instance. Leave it empty for the default/main instance.\\ |
| At line 20 changed 3 lines |
| Challenge type : Only available on V02.\\ |
| http-01-> It is an http based challenge it requires the CrushFTP to have an HTTP server item available from outside on port 80. Make you sure the https redirect is turned off. V01 can only do http based challenge.\\ |
| tls_alpn-> (!!! Only works with Java 11+) It is a tls based challenge it requires the CrushFTP to have an HTTPS server item available from outside on port 443.\\ |
| __Challenge Type:__ Available only with ACME v2.\\ |
| • http-01 -> This is an HTTP-based challenge and requires CrushFTP to have an HTTP Server item accessible __externally__ on port __80__.\\ |
| • tls_alpn -> (Only works with Java 11 or higher) This is a TLS-based challenge and requires CrushFTP to have an HTTPS Server item accessible __externally__ on port __443__.\\ |
| __⚠️ Note:__ Let’s Encrypt only validates __domain ownership__ via ports __80 (for HTTP-01 challenge)__ or __443 (for TLS-ALPN-01 challenge)__. Other ports (such as 444 or 8080) will not work for certificate issuance.\\ |
| At line 24 changed one line |
| Domains : Multiple domains should be separated with a comma.\\ |
| __Related CrushFTP Server port__: Must match the HTTPS port configured in your CrushFTP server item. Defaults to 443.\\ |
| At line 26 changed one line |
| Keystore: Set the location of the jks file, and the name.\\ |
| Notes: Freeform text field. Internal documentation or notes only. Has no effect on behavior.\\ |
| At line 28 changed one line |
| Staging flag: It is for __test mode__. If the is true it will only generate a dummy jks, not a valid one.\\ |
| __Domains:__ Enter one or more domains, comma-separated. Example:\\ |
| {{{ |
| example.com,ftp.example.com |
| }}}\\ |
| At line 30 changed one line |
| If the all fields are ready hit the submit, and the jks will be created in the specified key store location.\\ |
| __Keystore:__ Path (URL-style) to the .jks file that will be created/used to store the Let’s Encrypt certificate. |
| Example: |
| {{{file://var/opt/CrushFTP11/letsencrypt_keystore.jks}}}\\ |
| ⚠️ Must end in .jks\\ |
| At line 32 changed one line |
| Once done, and full success, there is another step. On Preferences_>Encryption_>SSL page, will need to supply the same full path to the key store (.jks) file and the passwords you entered on the Letsencrypt plugin. The plugin only generates the key store, but doesn't apply it. Once done, test, if successful, save, then restart the HTTPS port or the CrushFTP service, to actually load the cert. Then can test with a browser.\\ |
| __Keystore Password / Key Password__: Passwords used to protect:\\ |
| • The Java Keystore (Keystore Password)\\ |
| • The private key inside the keystore (Key Password)\\ |
| 🔐 These must be remembered for configuring [SSL] later in Preferences.\\ |
| At line 34 changed one line |
| Will need to click Submit and restart every 60-90 days , because the Let's encrypt cert is valid only for this long.\\ |
| __Organization Unit, Locality, State, Country Code, Email__: Used to populate the subject information in the certificate request (CSR). __Email__ is required by Let’s Encrypt and used for expiration notices.\\ |
| At line 36 changed 2 lines |
| __Update the certificate automatically:__ It updates the certificate automatically and restarts the https server item ports. Let's encrypt server allows 5-6 tries weekly, we suggest to set the check certificate weekly.\\ |
| __Alert:__ To get notification about failed updates create Plugin Message alert (Preferences -> Alerts). |
| __Optional Checkboxes__:\\ |
| • __Ignore Failing “Not a CrushFTP Server”:__ Skips verification that the target is a valid CrushFTP server. Use if the check causes problems and you’re sure the server is correct.\\ |
| • __Skip all pre-checks (DNS, CrushFTP server, etc)__: Bypasses all preliminary checks. Useful for troubleshooting.\\ |
| • __Replicate?__: Used in clustered environments. If enabled, the cert is also replicated to slave/replica nodes.\\ |
| At line 39 changed one line |
| !!!Troubleshooting\\ |
| Once all fields are completed, click the __Test__ button to validate your configuration. If the test is successful, click __Submit__ to generate the keystore at the specified location.\\ |
| At line 41 changed 4 lines |
| 0. Download replace plugin. Let's Encrypt often has change on the API. |
| 1. Check that your server is reachable through the given domain with http protocol on the default port (80) or on https on the default port (443).\\ |
| 2. Check Staging flag, it is a test mode. Always try first in test mode. Check the Delete account key pair and Delete domain key pair flags and test again.\\ |
| 3. Rewrite the Keystore Password and Key Password, test it again. |
| ✅__ Update the certificate automatically:__ Enables auto-renewal of the Let’s Encrypt certificate.\\ |
| __Update certs before__: __5__ days -> Starts renewal process 5 days before expiration.\\ |
| __Check certificate every__: __5__ days -> Interval between certificate validity checks.\\ |
| __Update info__: Shows the last time the certificate was checked.\\ |
| __Execute CrushTask/Job after cert renew__: After a successful renewal, runs a [CrushTask] or Job by name. Useful for actions like sending alerts.\\ |
| \\ |
| ⚠️__Note:__ After a successful generation, go to __Preferences → Encryption → [SSL]__ and enter the same full path to the .jks file, along with the passwords you specified in the Let’s Encrypt plugin. The plugin only generates the keystore — it does not apply it automatically.\\ |
| \\ |
| __Submit Button:__ Issues a new certificate or initiates a renewal based on the current configuration. ⚠️ Use this only after the __Test button__ has confirmed a successful setup.\\ |
| __Test Button:__ Immediately validates the current configuration and attempts a certificate request in staging mode to avoid rate limits. ⚠️ Always use this first to ensure your settings are correct.\\ |
| \\ |
| __Alert__: To receive notifications about failed certificate updates, create a __Plugin Message__ alert under __Preferences → Alerts__. |
| \\ |
| !!!Troubleshooting |
| \\ |
| __1.)__ Ensure your __CrushFTP Server__ is accessible over __HTTP (port 80)__ or __HTTPS (port 443)__ for the given __domain__.\\ |
| You can verify this by using a simple command like:\\ |
| {{{ |
| telnet yourdomain.com 80 |
| or |
| telnet yourdomain.com 443 |
| }}}\\ |
| If the connection succeeds, the port is open and reachable. If it fails, check your firewall, port forwarding, or network settings to ensure external access is allowed. |
| You can also use [yougetsignal open ports test link|https://www.yougetsignal.com/tools/open-ports/] to test your domain’s open ports from the internet.\\ |
| If the test fails:\\ |
| • Check your router’s port forwarding rules\\ |
| • Ensure no firewall (local or network) is blocking access\\ |
| • Confirm that CrushFTP is listening on the required ports in your Server Items\\ |
| \\ |
| __2.)__ Verify that the domain and ports point to the correct CrushFTP instance. Make sure the DNS for your domain resolves to the correct public IP address of your CrushFTP server.\\ |
| __⚠️ Note:__ Let’s Encrypt only validates domain ownership via ports __80__ or __443__, depending on the challenge type selected. Other ports (e.g., 444, 8080) will not work for certificate issuance.\\ |
| \\ |
| __3.)__Use test mode first: Always click the Test button before making a real certificate request. This validates your configuration and helps avoid hitting Let’s Encrypt rate limits during setup.\\ |
| \\ |
| __4.)__ Check the main CrushFTP.log for errors, especially rate limit issues. Look for entries such as __LetsEncrypt:Challenge result__ that may include error details.\\ |
| \\ |
| __Common Let’s Encrypt rate limit error types__:\\ |
| {{{ |
| SERVER|LetsEncrypt:Challenge result: { |
| "type": "tls-alpn-01", |
| "status": "invalid", |
| "error": { |
| "type": "urn:ietf:params:acme:error:rateLimited", |
| "detail": "Error creating new order :: too many certificates already issued for exact set of domains: example.com,www.example.com: see https://letsencrypt.org/docs/rate-limits/", |
| "status": 429 |
| } |
| } |
| }}}\\ |
| {{{ |
| SERVER|LetsEncrypt:Challenge result: { |
| "type": "tls-alpn-01", |
| "status": "invalid", |
| "error": { |
| "type": "urn:ietf:params:acme:error:rateLimited", |
| "detail": "Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/", |
| "status": 429 |
| } |
| } |
| }}}\\ |
| {{{ |
| SERVER|LetsEncrypt:Challenge result: { |
| "type": "tls-alpn-01", |
| "status": "invalid", |
| "error": { |
| "type": "urn:ietf:params:acme:error:rateLimited", |
| "detail": "Error creating new account :: too many registrations for this IP :: see https://letsencrypt.org/docs/rate-limits/", |
| "status": 429 |
| } |
| } |
| }}}\\ |
| Let’s Encrypt enforces strict rate limits to prevent abuse. If your request fails, check the logs for messages indicating you’ve hit a rate limit.\\ |
| Below are common limits and their reset windows:\\ |
| -__Duplicate Certificate Limit__:\\ |
| • Limit: 5 identical certificates per domain per week\\ |
| • Reset: 7 days after the first certificate issuance\\ |
| -__Certificates per Registered Domain__:\\ |
| • Limit: 50 new certificates per week for the same base domain (e.g., example.com)\\ |
| • Reset: 7 days\\ |
| -__Failed Validation Attempts__\\ |
| • Limit: 5 failed validation attempts per account, per hostname, per hour\\ |
| • Reset: After 1 hour\\ |
| -__Account Creation Limit__:\\ |
| • Limit: 10 new accounts per IP address every 3 hours\\ |
| • Reset: After 3 hours\\ |
| \\ |
