The server's certificate and authority
The console and the server's own certificate authority belong to the server, not to an instance, and both are managed on the bootstrap agent on port 5202. An instance's own certificate is on its Certificate tab: see Certificates.
The console's certificate
The console on port 5322 serves HTTPS with a self-signed certificate that ohm install issues for
the server's host name. The bootstrap agent renews it: its Certificate renewal operation, on the
agent's Maintenance page, runs every day and replaces the certificate when it nears expiry.
The console's certificate mode is chosen on the bootstrap agent on port 5202 - the Certificate tab of its Certificates page. To put your own certificate there, choose Custom mode and upload the certificate and its private key on that tab, or upload them from the command line, on the server or remotely:
pelmo$ ohm server certificate custom --certificate-file console.crt --key-file console.keyThe certificate file is PEM, optionally followed by its intermediates; the key is PEM, PKCS#8 or
PKCS#1, encrypted or not. For an encrypted key, --passphrase-file names a file holding the
passphrase, which is used once and never stored. Both files are read by the command, so neither the
key nor its passphrase lands in your shell history. The pair is checked against the name the console
is reached by, the same check an instance's upload gets, and a pair that does not fit is refused with
the reason before anything is stored.
Storing is not serving: the stored pair goes into service with a certificate request in Custom mode on the agent's Certificates page, or at the next scheduled renewal.
A certificate request there is not a job: the agent issues the certificate while you wait. When the certificate changes, the console and then the management API are restarted onto it, and Request certificate holds its loader until the management API answers again - usually about half a minute more - so the notice appears with the console back rather than while it restarts. If the management API does not answer within three minutes, the request is reported as failed with that reason: the new certificate is in place, and Core services or the API's log says why the API did not come back.
Changing the mode there, for example from Self-signed to Let's Encrypt, and pressing Request certificate puts that mode's certificate in place: a new one when the mode has none yet, or the one it already holds when it is still valid. Force is not needed to switch modes. It is only for reissuing the certificate that is already being served while it is still valid.
When a Let's Encrypt or Custom request does not take effect, the console keeps the certificate already in place, or gets a self-signed one, so that it stays reachable. The agent reports that as a warning with the reason, not as a success. For as long as the selected mode has no certificate of its own, the Certificate tab carries a standing warning that the console is served over the fallback certificate; it goes away once a request in that mode succeeds.
Let's Encrypt by DNS-01 needs a license that carries it; HTTP-01 needs no license. Saving DNS-01 on a server whose license does not carry it is allowed, and the agent warns at once that a request will keep the certificate in place until the license covers it.
The Current certificate card on that tab has a Server hostname row: the name the server is configured for, and the machine's own name beside it when the two differ. A badge after the names says whether the certificate covers them - Certificate covers the name, or Certificate does not cover followed by the name it misses - the same badge an instance's Configuration tab shows beside its FQDNs.
A machine renamed outside the installer, with hostnamectl or an edited /etc/hostname, keeps the
server's configured name, and the console, its links and every certificate request go on using it.
The Certificate tab then shows the new name with the warning badge and says the two differ. Request
certificate does not fix that, even with Force: it issues for the configured name again. Rename the
server instead (see Renaming the server).
Renaming the server
The agent's Configuration page carries the Server name card: the Configured name, the
Machine name (with a note when the machine was renamed outside the installer), the Public
name, and a New name field. The new name must be fully qualified, such as
console.example.com; Let's Encrypt and passkeys need one.
Request a certificate for the new name afterwards is on by default and requests a certificate in the configured mode once the server answers to the new name:
| Mode | What the rename does for the certificate |
|---|---|
| Let's Encrypt | Asks Let's Encrypt for the new name, the same request as Request certificate. The name must resolve to this server; until it does, the console keeps a self-signed certificate and the request says why |
| Custom | Serves the uploaded certificate again, if it covers the new name |
| Self-signed | Always issues a self-signed certificate for the new name |
With the switch off, the console is served over a self-signed certificate for the new name until you press Request certificate on the Certificates page.
Rename the server asks for a confirmation that says what will happen, then hands the rename to the host. The management plane is offline for a few minutes while the server is repaired under the new name, and the Odoo instances stop while their containers are recreated; they keep their own names. The console and the agent move to the new name, so the page tells you where to reach them next. When you open the page again, it says whether the rename succeeded or failed.
If the card says This host does not watch for a rename yet, the host was installed by an earlier
version: run sudo ohm install on the host once, or rename on the host itself.
On the host, the same rename runs from the command line. It asks for a confirmation unless you pass
--yes, and --no-certificate leaves the certificate request out:
$ sudo ohm server rename console.example.comThe installer renames too, when it is given a name that differs from the configured one:
sudo ANTELAO_INSTALL_HOSTNAME=new.example.com ohm install
The console's public name
Let's Encrypt only issues certificates for a fully qualified name, one with at least one dot such
as console.example.com. A server installed under a machine name such as odoo01 cannot get one
for that name, and the Certificate tab says so for as long as the host name is a machine name.
Set Public name on the Provisioning card of the agent's Certificate tab to the name the console is reached by from the internet, and Save. From then on:
- Let's Encrypt is asked for the public name, with either challenge. Without a public name it is asked for the host name, and only when the host name is fully qualified.
- The Current certificate card checks the certificate against the public name.
- The self-signed fallback certificate covers the public name too.
- The consoles published on port 443, when a rule publishes one, answer the public name.
- Passkeys are bound to the public name (see Passkeys).
Saving LetsEncrypt mode is refused, with the reason, while there is neither a public name nor a fully qualified host name. The host name itself stays what the installer set; rename the server with the installer when the machine name should go altogether.
When Let's Encrypt refuses a request, the notice says which step refused it: the order itself (a name it does not issue for, a rate limit, the domain's CAA record) or the challenge. While testing, switch Staging environment on: staging certificates are not trusted by browsers, but they do not count against Let's Encrypt's rate limits.
Every save, request, upload, removal and authority change made on the agent's Certificates page is recorded under Security > Audit, with agent as its source, as soon as the management API is running, and the console's server configuration follows the new certificate options.
The certificate belongs to the server, not to the management console that happens to be serving at the time, and the agent is what survives the console being recreated - so the agent is where it is decided.
Reach the console by name rather than by address. A passkey's relying-party id must be a domain, and the certificate carries DNS names only.
The server's own certificate authority
Every certificate the server issues itself - the console's and the instances' self-signed ones - is signed by one authority of the server's own. Import that authority once into a browser or an operating system and all of them are trusted together, instead of accepting a warning per instance.
That is what the code editor's panels need to load at all, so a server people write code on wants this settled early.
Managing the authority
On the bootstrap agent's Certificates page, the Root CA tab. Create one with a name, organisation, validity and key size of your own; renew one on its existing key; and delete one nothing is issued under.
Renewing on the existing key is the useful property: certificates already issued under it stay valid, so a renewal is not a re-trust exercise for everyone.
The trust kit
Every authority offers a trust kit download, from the agent's Certificates page and from an instance's Certificate tab. It carries the authority in both encodings, a README with the steps for Windows, macOS and Linux, and an installer script for each.
Hand that to whoever needs to trust the server, rather than a .crt and a paragraph of instructions.
The README also covers the ohm command line on another machine. A connection can trust the
server's authority for that connection alone, without importing anything into the machine's trust
store, by naming the kit's .crt file:
$ ohm connection add --name pelmo --url https://pelmo.example.com:5312 --ca-file pelmo-ca.crtThe connection keeps the file's path and checks the server's certificate against it on every call,
so keep the file where it is. --certificate-sha256 pins the server's own certificate by its
SHA-256 fingerprint instead, whoever issued it; give one or the other, not both. When ohm does not
trust a server, its message names the certificate's fingerprint and these two ways to trust it. A
connection that pins the console's certificate stops working when that certificate is reissued: add
it again with the new fingerprint, or with the CA file.
Choosing one
The Self-signed card on an instance's Certificate tab takes a Root CA as its first field, so an instance can be issued under a different authority from the server's default when it needs to be.