Onyx VoiceDocumentation
All chapters

Docs / Running the server

Updates

An Onyx Voice server gets two kinds of updates through the same channel: Ubuntu's own updates, security fixes above all, and new versions of Onyx Voice. This chapter covers installing them from the console, from the console menu and from the command line, what happens to calls while they install, servers without internet, and clusters.

Where updates come from

The server uses Ubuntu's normal package sources for Ubuntu's updates, and the signed Onyx Voice repository at https://onyxvoice.net/apt for the two Onyx Voice packages:

  • onyx-voice: the control plane, the web console and portal, phone provisioning, the onyx command and the server tools.
  • onyx-voice-engine: the phone engine.

The server trusts the Onyx Voice archive key for this repository only. The repository is configured in /etc/apt/sources.list.d/onyx-voice.sources.

Which updates the server installs

Only the updates a phone system needs are offered:

  • Onyx Voice: new versions of onyx-voice, onyx-voice-engine and onyx-voice-speech.
  • Security: Ubuntu's security fixes.

A server installed before a package existed gets it with its next update: the list shows onyx-voice-speech (the voices greetings are made in on the server, about 360 MB) as Onyx Voice · new. It is added once; if you remove it afterwards, updates leave it off.

Ubuntu's other updates (bug fixes and changes in packages, many of which a phone system never uses) are left out. The Updates card names them under the list and does not install them. If a needed update depends on a newer version of another package, that package comes along with it.

Checking for updates

The server checks for updates by itself every 5 minutes, starting two minutes after it boots. It installs nothing during this check. While Server › System & updates is open, the Updates card follows these checks by itself.

When a new version of Onyx Voice is available, the menu at the bottom left of the console shows Update available: v_version_ to system administrators. Otherwise it shows Check for updates. Both open Server › System & updates.

Automatic security updates

Ubuntu installs its security fixes by itself once a day. The Updates card shows Security updates install automatically, with the last automatic install. Select Turn off to install them yourself from the card instead, and Turn on to let Ubuntu install them again.

Automatic updates never restart a service, and never restart the server. A service that uses an updated library (OpenSSL, for example) keeps running the old one until it restarts. The card then lists those services: restart them in the Services card when it suits you. Restarting the phone engine or the database drops calls; in a cluster, switch over first (see High availability).

Updating from the console

  1. Open Server › System & updates. The Updates card says when updates were last checked and how many there are to install, with how many are security updates. A new version of Onyx Voice also shows as Onyx Voice _version_ is available.
  2. Select Check for updates to check again now. The server refreshes its package lists; a progress bar shows how far it is. When it is done, the card lists the updates to install, with their version change (Version) and an Onyx Voice or security label.
  3. If an update needs a restart of the server to finish (a new Linux kernel, for example), you can tick Restart automatically if needed. Leave it unticked to restart later yourself.
  4. Select Install. The button says how many updates it installs.

The updates install as a job. A progress bar shows how far it is, with the step it is on (downloading, unpacking or setting up a package); Show details shows the full output. The job keeps running if you leave the page or if Onyx Voice restarts during it: while Onyx Voice restarts, the page says it is waiting for the server and catches up when the console is back. If the 5-minute check happens to be running when you select Install, the job waits for it first. Configuration files you have changed are kept. When it is done, the job's message says how many updates were installed and whether a restart is needed.

If a restart is needed and you did not tick the box, the System page shows Installed updates need a restart to finish, with the packages that asked for it. Restart in the Restart or shut down card when it suits you (see Server tools). With the box ticked, the server restarts one minute after the updates are installed.

If some package source could not be reached, for example because the server cannot reach onyxvoice.net, the card shows a warning such as Some package sources could not be refreshed, and the updates from the other sources still install. One unreachable source never holds back Ubuntu's security fixes.

The console menu on the server's screen has the same under System: updates, time, services, restart › Updates: Check now, Install updates (security fixes and Onyx Voice) and Show available updates. The list shows the left-out updates separately.

What happens to calls

What is updatedWhat happens
Ubuntu packagesNothing the phones notice: services that use an updated library (OpenSSL, for example) keep running the old one until they restart. Neither the job nor the automatic security updates restarts them. The job's message and the Updates card list them; restart them on System & updates when it suits you. If the phone engine or the database is among them, its restart drops calls (in a cluster, switch over first, see High availability). A kernel update needs a restart of the server to take effect.
onyx-voiceOnyx Voice restarts. The web console, portal and phone provisioning are unavailable for a few seconds. Calls in progress continue.
onyx-voice-engineThe engine restarts. Calls in progress drop. Phones and trunks register again within a minute.
Server restartPhones cannot call until the server is back. Calls in progress drop.

Look for onyx-voice-engine in the update list; the job's output also says when the phone engine is among the updates, and the console menu's list marks it (drops calls). Install engine updates and restarts outside business hours.

Updating from the command line

Over SSH, or from Open a shell in the console menu, the usual Ubuntu commands work. To install only Onyx Voice, for example:

sudo apt update
sudo apt install --only-upgrade onyx-voice onyx-voice-engine onyx-voice-speech

sudo apt upgrade installs every update, the ones the console leaves out included. The same notes apply: an engine update drops calls in progress. The Updates card in the console shows what you installed this way after its next check.

Turning the Onyx Voice source on or off

A server without internet access cannot reach onyxvoice.net. Turn the Onyx Voice source off there, so checks do not keep reporting it:

  1. Open Server › System & updates.
  2. The Updates card shows Onyx Voice updates on with the repository's address. Select Turn off.

The card then shows Onyx Voice updates off. Select Turn on to use it again, then Check for updates to see what is new.

On a server without internet, install new Onyx Voice versions from the packages instead: download onyx-voice-engine_<version>_amd64.deb, onyx-voice_<version>_amd64.deb and onyx-voice-speech_<version>_amd64.deb from the download page at onyxvoice.net (they are also in the onyx folder of each installer ISO), copy them to the server and install them together:

sudo apt install ./onyx-voice-engine_*_amd64.deb ./onyx-voice_*_amd64.deb ./onyx-voice-speech_*_amd64.deb

Such a server gets no Ubuntu updates either, unless it can reach an Ubuntu package mirror on your network.

Servers installed from 0.1.0

Servers installed from version 0.1.0 have the Onyx Voice source switched off. Turn it on once with this command on the server, over SSH or from the console menu's shell:

sudo sed -i -e 's#^URIs:.*#URIs: https://onyxvoice.net/apt#' -e 's#^Enabled:.*#Enabled: yes#' /etc/apt/sources.list.d/onyx-voice.sources

From then on the server updates like any other: select Check for updates in the Updates card, or run sudo apt update.

Updating a cluster

In a cluster of two servers, update one server at a time so the phone system keeps running:

  1. Update the standby server.
  2. Switch over, so the updated server becomes the active one. Calls in progress drop at the switchover; phones keep their registrations.
  3. Update the other server, which is now the standby.

See High availability for the switchover and for checking that both servers are healthy before you start.

Checking the version

The System page shows the installed Onyx Voice version and the engine's version at the top. From a shell, dpkg-query -W onyx-voice onyx-voice-engine shows both. A backup can only be restored onto a server with the same version or newer, so update a replacement server before restoring onto it (see Backup and restore).