GoAdmio

miniossl

Get or renew the SSL certificate for the MinIO hostname (Let's Encrypt or Buypass), copy it into MinIO, and restart the service

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:

[!WARNING] Run minio first. 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:

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:

  1. creates /backup/s3 and the certs folder if missing
  2. copies fullchain.pem to public.crt and privkey.pem to private.key in /usr/local/goadmio/minio/.minio/certs/
  3. sets minio as the owner of the install folder and /backup/s3
  4. runs setcap 'cap_net_bind_service=+ep' on the MinIO program, so the non-root minio user can listen on port 443
  5. restarts the minio service

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"]
  1. Appends the command line to /var/log/go/miniossl.log.
  2. Reads the hostname from /etc/minio, and the OS and web server type from /usr/local/goadmio/linux/os.db and ws.db.
  3. Reads the days left on the hostname's certificate and prints them.
  4. If fewer than 30 days remain, deletes the certificate with certbot and removes its live and archive folders.
  5. Removes public.crt and private.key from MinIO's certs folder.
  6. If minio.conf uses port 443, stops and disables the web server and all PHP-FPM services.
  7. If no certificate folder exists or --force was passed, deletes any certbot entry for the hostname and requests a new certificate.
  8. If a certificate folder now exists, copies the files into MinIO, fixes ownership, runs setcap, and restarts minio.
  9. 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