| At line 1 added one line |
| \\ |
| At line 3 changed one line |
| This plugin is possible starting with CrushFTP v9. You need to download this plugin and place it in your Crush folder, plugins folder. [LetsEncrypt.jar]\\ |
| ---- |
| __⚠️ 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 5 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/])\\ |
| ---- |
| 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 8 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.\\ |
| 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 one line |
| [attachments|lets_encrypt_header.png]\\ |
| At line 12 changed one line |
| Domains : Multiple domains should be separated with a comma.\\ |
| ✅ __Enabled__: Turns the Let’s Encrypt plugin on so it runs and attempts to manage certificates.\\ |
| At line 14 changed one line |
| Keystore: Set the location of the jks file, and the name.\\ |
| ✅ __Debug__: Enables verbose logging to help diagnose issues during certificate generation or renewal.\\ |
| At line 16 changed one line |
| Challenge Path : Must set the WebInterface folder from the CrushFTP install folder.\\ |
| __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 18 changed one line |
| Cacert Key: Java default system keystore (cacerts) the default password for it is "changeit".\\ |
| __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 20 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.\\ |
| __Related CrushFTP Server port__: Must match the HTTPS port configured in your CrushFTP server item. Defaults to 443.\\ |
| At line 22 changed 2 lines |
| If the all fields are ready hit the submit, and the jks will be created in the specified keystore location.\\ |
|
| Notes: Freeform text field. Internal documentation or notes only. Has no effect on behavior.\\ |
| \\ |
| __Domains:__ Enter one or more domains, comma-separated. Example:\\ |
| {{{ |
| example.com,ftp.example.com |
| }}}\\ |
| \\ |
| __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\\ |
| \\ |
| __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.\\ |
| \\ |
| __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.\\ |
| \\ |
| __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.\\ |
| \\ |
| 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.\\ |
| \\ |
| ✅__ 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\\ |
| \\ |
