> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-mioty-service-center/security/certificate-renewal.md).
# Certificate renewal
Renew a KiloCenter server certificate while preserving the existing certificate authority and stored data.
The installation operator uses this procedure when the server certificate is nearing expiry or its hostname must change. Keep the existing certificate authority (CA) and its private key. A routine server renewal does not require deleting Docker volumes, the database or station registrations.
Use a maintenance window: base station and application-center connections will pause when KC-Core stops. First try this procedure on an isolated copy of your installation. The certificate tool's server-only behavior has been tested; every installed container version and recovery arrangement must still be checked by its operator.
The **Certificates** page of the web interface shows how long the server certificate and each base station certificate remain valid, and flags one that **Expires soon**.
## Can I renew the server certificate from the web interface?
Yes. An **Admin** can renew it without stopping KC-Core. Open **Certificates**, select **Renew Server Certificates** and read the dialog. It lists the **Names on the new certificate**: the host of `protocol.bsci_external_url`, the names in `certificates.server_names` and every name the current certificate already carries. A new server certificate is issued for those names, valid for `certificates.server_validity_days` (365 by default) and signed by the same CA. The service center serves it from the next connection on, and connected base stations keep their session. A base station that connects by a name missing from the list fails hostname verification, so add the name to `certificates.server_names` and restart KC-Core before you renew. Select **Renew Server Certificates** again to confirm; the page reads "Server certificates renewed".
On a fresh installation without a server certificate the same place shows **Generate Server Certificates** instead ("Server certificates generated"). Renewal needs the CA certificate and the CA private key in the certificates directory; if either is missing, the request fails and you must follow the command-line procedure below or restore them from your backup.
The procedure below stays the right choice when you want a verified, recoverable maintenance window, when the web interface cannot reach KC-Core, or when the hostname must change in a way the dialog does not list.
## Before changing files
1. Confirm the installation, existing image and intended hostname. Use the same Compose project and files as the running installation. Do not change images as part of this procedure.
2. Make a restricted, recoverable backup of the existing certificate directory and confirm that the CA certificate, CA private key, server certificate and server private key are present. Preserve file ownership and permissions. Keep private keys out of Git, tickets and shared logs. Confirm the backup can be restored before proceeding.
3. Confirm you have `openssl` available to verify the result. If the CA or backup is missing, stop. Do not run initial certificate generation to work around a missing CA.
## Docker Compose installation
Run from the repository root, using the installation's normal Compose options. Replace `your-hostname.example.com` with the hostname stations will actually use.
1. Stop the service that loads the server certificate:
```bash
docker compose stop kilocenter
```
2. Renew only the server certificate and key in the existing certificate volume:
```bash
docker compose run --rm --no-deps --pull never --entrypoint certgen certgen \
-dir /app/certificates -server-only -server your-hostname.example.com -days 365
```
The explicit entrypoint matters: the normal `certgen` service starts a shell for first-install checks. If this command fails, leave KC-Core stopped and follow the failure steps below.
3. Copy only the public CA and server certificates into a temporary verification directory using `docker compose cp kilocenter:/app/certificates/ca.crt` and the corresponding `server.crt` path, each followed by your chosen local destination. Compare the CA certificate with the backup; it must be unchanged. Verify the new server certificate:
```bash
openssl verify -CAfile ca.crt -verify_hostname your-hostname.example.com server.crt
```
4. Only after verification succeeds, start KC-Core:
```bash
docker compose start kilocenter
```
5. Check service health and confirm that a known station and, if used, application center reconnect. Keep the maintenance time, hostname, public certificate fingerprint and result. Update the configured hostname for future maintenance. Remove temporary public-certificate copies.
## Linux-host installation
Stop KC-Core with the installation's normal service manager and back up the certificate directory. Run its existing `certgen` tool with the same certificate directory and `-server-only`, as above. Verify the unchanged CA and new hostname before restarting KC-Core. Then check reconnection and retain the result. Do not regenerate the CA.
## If renewal or reconnection fails
Keep KC-Core stopped. Restore the backed-up server certificate **and its matching private key** with the original ownership and permissions. Verify that they match and that the CA is unchanged, then restart and check the previous connection. If the old certificate has expired, its key is compromised, or the backup is unavailable, do not restore service with invalid trust or disable verification. Keep the service isolated and obtain installation support. Do not reset data volumes.
A compromised or expired CA requires a separate trust-replacement procedure and coordinated station updates. This server-only procedure is not suitable for that case.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.kiloiot.io/kilo-mioty-service-center/security/certificate-renewal.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
