miniossl
Get or renew the SSL certificate for the MinIO hostname (Let's Encrypt or Buypass), copy it into MinIO, and restart the service
- Command:
/go/miniossl - Category: Storage
- Required option: None
- Output: Plain text
- Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/miniossl makes sure MinIO has a working HTTPS certificate. It reads the hostname saved by minio, and:
- checks how many days the hostname's certificate has left, and discards it when fewer than 30 remain
- requests a new certificate from Let's Encrypt (or Buypass) if none exists
- copies the certificate and private key into MinIO's
certsfolder - allows the MinIO program to listen on port 443 without running as root
- restarts the
minioservice
[!WARNING] Run
miniofirst. This command takes the hostname from/etc/minio. If that file is missing or empty, the cleanup step can delete every Let's Encrypt certificate on the server. See Before you run it.
[!WARNING] If MinIO is set to use port 443 (
minio -s y), this command stops and disables the web server and all PHP-FPM services. Every website on the server goes offline, and nothing starts them again.
Quick start
# Install or renew the certificate for the hostname saved by minio
/go/miniossl
Syntax
/go/miniossl [--force] [--buypass]
All options are optional flags. Run the command as root.
Options
| Option | Effect |
|---|---|
--force |
Delete the existing certificate for the hostname and request a new one, even if the current one is valid. |
--buypass |
Request the certificate from Buypass instead of Let's Encrypt. |
Both flags are detected anywhere in the arguments, and any other argument is ignored without an error. They can be combined.
Output
The command prints plain text, not JSON. During certificate requests it also shows certbot's own messages.
| Message | Meaning |
|---|---|
SSL certificate for <hostname> expires in <N> days. |
The days left on the current certificate. See the 0 days message. |
Installing SSL Certificates on MinIO Server Hostname <hostname>... |
A certificate exists and is being copied into MinIO. |
Can not install SSL (<hostname>) |
No certificate exists for the hostname after the request, so nothing was installed. |
Every run is also appended to /var/log/go/miniossl.log.
Examples
# Install the certificate, or renew it when fewer than 30 days remain
/go/miniossl
# Replace the certificate now, even if it is still valid
/go/miniossl --force
# Use Buypass instead of Let's Encrypt (for example, after hitting Let's Encrypt rate limits)
/go/miniossl --buypass
# Check the hostname the command will use, and the certificate status
cat /etc/minio
certbot certificates
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Can not install SSL (<hostname>) |
The certificate request failed. | Check that the hostname's DNS points to this server and port 80 is open, then see the next row. |
| Certificate request fails while MinIO is on port 3333 | The request uses certbot's standalone mode, which needs port 80, and the web server is still running on it. | Stop the web server briefly and run again, or use a different method to place the certificate. See Certificate request. |
expires in 0 days but a certificate exists |
See the 0 days message. | Check with certbot certificates. |
| Every website went offline | MinIO uses port 443, so the web server and PHP-FPM were stopped. | See Web server and PHP-FPM. |
| All Let's Encrypt certificates are gone | /etc/minio was missing or empty. |
See Before you run it. Reissue the certificates with ssl or installssl. |
| MinIO has no certificate after a failed run | The old certificate was deleted before the new request failed. | Fix the cause, then run /go/miniossl again. |
| Rate limit error from Let's Encrypt | Too many certificates were requested for the hostname, often from repeated --force. |
Wait, or run with --buypass. |
| MinIO cannot start on port 443 | The permission to use port 443 was lost, for example after reinstalling MinIO with minio. |
Run /go/miniossl again. |
| Hostname is blank in the messages | /etc/minio is missing. |
Run minio first. |
Details
Before you run it
The hostname comes from /etc/minio, which minio writes. The cleanup step removes /etc/letsencrypt/live/<hostname> and /etc/letsencrypt/archive/<hostname>. If the hostname is empty, those paths become the parent folders themselves, which hold the certificates of every hosted domain. Check the file first:
cat /etc/minio
The 0 days message
The command reads the remaining days from certbot certificates. If that output has no "days" line (no certificate exists, the certificate is expired, or certbot could not run), the value becomes 0. The command then prints expires in 0 days and treats the certificate as due for replacement. The message is therefore misleading in those cases.
Replacing the certificate
When fewer than 30 days remain, the command deletes the hostname's certificate from certbot and removes its folders under /etc/letsencrypt. It also removes MinIO's current public.crt and private.key on every run. The old certificate is deleted before the new one is requested, so if the request fails, MinIO is left without a certificate until you run the command again.
Let's Encrypt certificates are valid for 90 days. Nothing in this command schedules it, so run it periodically to keep the certificate from expiring.
Certificate request
A new certificate is requested only when none exists for the hostname, or when --force is passed. The request:
- uses certbot's standalone mode, which needs port 80 to be free
- uses
info@<hostname>as the contact email - uses Let's Encrypt, or Buypass (
https://api.buypass.com/acme/directory) with--buypass - requires the hostname's DNS to point to this server
Free port 80 is only guaranteed when MinIO uses port 443, because that is the only case where the command stops the web server first. On the default port 3333 setup, the web server keeps running, so the request fails unless you stop it yourself.
Web server and PHP-FPM
If /usr/local/goadmio/minio/minio.conf contains :443 , MinIO is using port 443, and the command stops and disables:
| Server type | What is stopped |
|---|---|
| AlmaLinux, Rocky, CentOS, Red Hat, Fedora | httpd or nginx, and every Remi PHP-FPM service found under /etc/opt/remi |
| Debian, Ubuntu | apache2 or nginx, and every phpX.Y-fpm service found under /etc/php |
To bring websites back, MinIO must move off port 443: run minio again without -s y, which restarts the web server, then re-enable and start the PHP-FPM services.
Installing the certificate
If a certificate exists for the hostname, the command:
- creates
/backup/s3and thecertsfolder if missing - copies
fullchain.pemtopublic.crtandprivkey.pemtoprivate.keyin/usr/local/goadmio/minio/.minio/certs/ - sets
minioas the owner of the install folder and/backup/s3 - runs
setcap 'cap_net_bind_service=+ep'on the MinIO program, so the non-rootminiouser can listen on port 443 - restarts the
minioservice
The setcap permission is attached to the program file. minio replaces that file on every run, so run /go/miniossl again after reinstalling.
What it does
flowchart TD
A["miniossl ..."] --> B["Read hostname from /etc/minio"]
B --> C["Check days left on certificate"]
C --> D{"Fewer than 30 days?"}
D -- "Yes" --> E["Delete certificate and its folders"]
D -- "No" --> F
E --> F["Remove MinIO's copy of the certificate"]
F --> G{"MinIO on port 443?"}
G -- "Yes" --> H["Stop and disable web server and PHP-FPM"]
G -- "No" --> I
H --> I{"No certificate, or --force?"}
I -- "Yes" --> J["Request new certificate"]
I -- "No" --> K
J --> K{"Certificate exists?"}
K -- "Yes" --> L["Copy to MinIO, setcap, restart minio"]
K -- "No" --> M["Can not install SSL"]
- Appends the command line to
/var/log/go/miniossl.log. - Reads the hostname from
/etc/minio, and the OS and web server type from/usr/local/goadmio/linux/os.dbandws.db. - Reads the days left on the hostname's certificate and prints them.
- If fewer than 30 days remain, deletes the certificate with certbot and removes its
liveandarchivefolders. - Removes
public.crtandprivate.keyfrom MinIO'scertsfolder. - If
minio.confuses port 443, stops and disables the web server and all PHP-FPM services. - If no certificate folder exists or
--forcewas passed, deletes any certbot entry for the hostname and requests a new certificate. - If a certificate folder now exists, copies the files into MinIO, fixes ownership, runs
setcap, and restartsminio. - Otherwise prints
Can not install SSL (<hostname>).
See also
| Command | Description |
|---|---|
minio |
Install MinIO (S3-compatible object storage) as a service |
bucket |
Create a MinIO bucket, make it public or private, or create an S3 access key |
ssl |
Install an SSL certificate for a domain in GoAdmio |
installssl |
Install Let's Encrypt SSL on GoAdmio |
checkssl |
Audit SSL certificates for all hosted domains, renew those close to expiry, and send expiry alerts |
allow |
Open a TCP port in the server firewall |