Certificates

Navigate to System > Certificates to manage the TLS certificates Koios uses to identify itself — to browsers, and to the devices it connects to.

The page has two tabs:

The two are unrelated. Replacing one has no effect on the other.

Web Interface

Out of the box Koios serves a built-in self-signed certificate on the HTTPS port. It encrypts the connection, but no browser trusts it, so every user sees a security warning and has to click through it before reaching the login page.

Upload a certificate signed by a certificate authority your browsers already trust — your organization's internal CA, or a public one — and the warning goes away.

Active Certificate

The Active certificate card shows what is being served right now, with a badge naming where it came from:

Below the badge, the card lists the certificate's details:

• Common name and Issuer
• Subject alt names, when the certificate carries any
• Valid from and Valid until, with a badge counting the days remaining
• Serial and the SHA-256 fingerprint

The expiry badge reads Expires in 42d while the certificate is valid — teal normally, yellow at 30 days or fewer remaining, red at 15 or fewer. Once the date has passed it turns red and counts up instead, reading Expired 3d ago. Koios does not raise an alarm or an event when a certificate is about to expire, so check this card as part of your regular maintenance.

What You Need

Two files are required, plus an optional third. All are PEM encoded:

The certificate's common name or subject alt names should match the hostname or IP address your users type to reach Koios. A certificate that is valid but issued for a different name still produces a browser warning.

If your key is passphrase-protected, strip the passphrase before uploading:

openssl rsa -in encrypted.key -out koios.key

Installing a Certificate

1. Open the Web interface tab
2. In the Upload a certificate card, select your Certificate (PEM) file
3. Select the matching Private key (PEM) file
4. If your CA issued intermediates, select the Chain / intermediates file
5. Click Upload & apply

Koios validates the files before doing anything with them, then applies the certificate and reloads the web server without dropping connections. There is no restart and no downtime. Reload the page afterward if your browser is still showing the old certificate.

Uploading requires the Can manage HTTPS certificates permission, listed under System Settings in the role editor and held by the built-in Administrator role. Without it the form and the revert button stay visible but disabled, with a tooltip explaining why. See Roles & Permissions.

If the Upload Is Rejected

Validation runs before anything is applied, and the certificate currently in use stays live. Expect a rejection when:

• The certificate or key is not valid PEM
• The private key does not match the certificate
• The certificate has expired, or is not valid yet
• The key is passphrase-protected
• The certificate or chain file contains a private key — upload the key only in the key field

If the files pass validation but the web server refuses the result, Koios rolls back to the previous certificate and reports the failure. In every failure case the interface you are using stays reachable.

Reverting to Self-Signed

When a certificate uploaded through this page is active, a Revert to self-signed button appears on the Active certificate card. It removes the uploaded certificate and key and restores the built-in one. A confirmation dialog appears first, since browsers start warning again immediately afterward.

The button is not offered for the built-in certificate or for one placed on the server as a file — there is nothing to remove in the first case, and the second is not managed from here.

Certificates Placed on the Server

A certificate placed directly on the certificates volume takes precedence over anything uploaded through this page. This is the path to use when certificates are issued and rotated by automation rather than by hand.

While one is active, the badge reads Operator file drop, the upload form is disabled, and a note explains that the certificate must be removed from the server to hand control back to the interface.

For the file names, the exact location, and how to install a certificate this way at deploy time, see Environment Variables.

When TLS Is Disabled

If Koios runs with TLS disabled — typically because a load balancer or reverse proxy in front of it terminates HTTPS — none of this applies. Koios serves plain HTTP and the certificate presented to users is the one on your proxy. The tab still loads, but nothing it shows is in the path browsers use.

OPC-UA Clients

The OPC-UA clients tab is the central manager for the client certificates Koios presents when connecting to OPC-UA servers with a security mode of Sign or Sign & Encrypt. Generate or upload certificates here once, then assign them to devices in each device's connection settings. Devices with no certificate assigned use the default one.

Managing these certificates requires the Can manage OPC-UA certificates permission, listed under OPC-UA Certificates in the role editor and held by the built-in Engineer and Administrator roles. It also gates the private key download. This is separate from the web interface certificate permission above.

This tab replaced the certificate controls that used to live on the OPC-UA protocol detail page; that page now links here instead.

For generating, uploading, regenerating, assigning, and getting an OPC-UA server to trust a Koios certificate, see OPC-UA Certificates.

Auditing

Certificate uploads and reverts are recorded in the audit trail, along with who performed them. Private key material is never written to the record. See Audit Log.

What's Next

• OPC-UA Certificates: the full guide to OPC-UA client certificates
• Environment Variables: TLS settings and installing a certificate at deploy time
• Roles & Permissions: grant certificate management to a role