Troubleshooting

Start with sudo ows status and sudo ows logs. Most problems show up there.

OWS doesn’t start

sudo ows prints why. If the message scrolled away, see /opt/osop/ows/log/run.log.

Message

What to do

Docker is not installed or not running (installer)

Install Docker Engine (Installation), or start it: sudo systemctl start docker.

OWS image ... is missing

Run ows-install.sh again. Your configuration and license are kept.

ows needs root

Use sudo ows.

port is already allocated / address already in use

Another program uses port 16032. Stop it, or set another LISTEN_PORT and tell your clients.

A license message

See License messages below.

License messages

Message

What to do

no license file found

Save the license from OSOP as /opt/osop/license/ows.key (exactly that name). If you don’t have one yet, send the machine ID that OWS prints to OSOP (License).

the license is for a different computer

The license was made for another machine ID. Check sudo ows id against the ID you sent; if OWS moved to a new computer or VM, send the new ID to OSOP.

the license has expired

Contact OSOP to renew it.

the license is for a different OSOP product

The file is the license of another OSOP program. Each program has its own license file.

the license file is damaged or not an OSOP v3 license

The file was changed (for example by an editor or a copy that altered line endings) or is a license for an older OWS version. Save the original file again; if it is from an older version, see License.

the license file was altered or is not genuine

The file’s content was changed. Save the original file again, unchanged.

the license was not issued for this version of the software

Contact OSOP.

this computer has no unique hardware ID / the hardware ID is not coming from this computer

Contact OSOP and include the diagnostic lines OWS prints. On WSL 2 or Docker Desktop, use a Linux computer or a Linux virtual machine instead (Installation).

Clients can’t connect, or wait forever

  1. Is OWS running? sudo ows status.

  2. Can OWS reach the SeedLink server? OWS only starts answering clients once it has reached the SeedLink server. If it can’t, sudo ows status still says running, but clients get no answer and nothing new appears in the log. Check sources.seedlink.host and sources.seedlink.port:

    • SeedLink on the same computer: use host.docker.internal, not 127.0.0.1 or localhost. The SeedLink server must also accept connections from Docker’s network, not only from 127.0.0.1.

    • SeedLink on another computer: check that this computer can reach it, for example with nc -vz <host> 18000.

    To test OWS without SeedLink, set sources.seedlink to false and sudo ows restart.

  3. Firewall. Clients on other computers need TCP port 16032 (your LISTEN_PORT) open on the OWS computer.

  4. Same computer works, others don’t? Try getmenu localhost:16032 on the OWS computer (Check that it works). If that works, the problem is the network or firewall between the computers.

Channels are missing

  • A station from SeedLink is missing. OWS uses the station list it saved when it first connected. Delete the saved list (New stations on the SeedLink server).

  • A station from the archive is missing. Check that its files follow the SDS layout (SDS archive layout) and that ARCHIVE_DIR points at the archive’s root folder (the folder that contains the year folders). OWS finds new channels in the archive within about 30 seconds.

  • Nothing at all. Check both sources.seedlink and sources.sds, and sudo ows logs.

Helicorders show only the last few minutes

Live data from SeedLink covers only the last 5 minutes (sources.seedlink.ring_size). Everything older comes from the archive. Check that sources.sds is true and ARCHIVE_DIR points at an archive that is being written, for example by SeisComP’s slarchive.

Known limitations

  • Channel time range. For channels that exist only in the archive, the channel list (Earthworm getmenu, ObsPy’s get_availability()) can show the same start and end time. The data itself is served correctly.

  • Log lines [ERROR] CachingReader: ... std::invalid_argument ... stoi. They appear when OWS reads from the archive and are harmless: the data is read and served correctly.

  • Many clients. See Running OWS, Capacity.

Still stuck?

Contact OSOP (Support) with:

  • the output of sudo ows status, sudo ows check and sudo ows logs 200;

  • /opt/osop/ows/config/ows.conf and ows-host.conf;

  • what you tried and what happened.