# LetsEncrypt plugin

### LetsEncrypt plugin

---

**🛑 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**

---

**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).

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.

![Lets encrypt header](LetsEncrypt-plugin/lets_encrypt_header.png)\
![Lets encrypt](LetsEncrypt-plugin/lets_encrypt.png)

✅ **Enabled**: Turns the Let’s Encrypt plugin on so it runs and attempts to manage certificates.

✅ **Debug**: Enables verbose logging to help diagnose issues during certificate generation or renewal.

**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](DMZ.md) node) the certificate should be generated for. Let’s Encrypt will challenge that server instance. Leave it empty for the default/main instance.

**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**.

• **dns-01** -> See more info at [LetsEncrypt_dns01 Link](LetsEncrypt_dns01.md)

🛑 **Important:** 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.

**Related CrushFTP Server port**: Must match the HTTPS port configured in your CrushFTP server item. Defaults to 443.

Notes: Freeform text field. Internal documentation or notes only. Has no effect on behavior.

**ACME Files Path:** Specifies the local directory path where the Let's Encrypt (ACME) integration saves essential cryptographic and validation data.

**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](SSL.md) 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](CrushTask.md) or Job by name. Useful for actions like sending alerts.

🛑 **Important:** After a successful generation, go to **Preferences → Encryption → [SSL](SSL.md)** 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**.

---

**High Availaibility Configurations**: [LetsEncrypt High Availability](LetsEncrypt-High-Availability.md)

---

## 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.\
**🛑 Important:** 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
