diff --git a/www/troubleshooting.html b/www/troubleshooting.html index 948b0102b..ff3dff078 100644 --- a/www/troubleshooting.html +++ b/www/troubleshooting.html @@ -5,7 +5,7 @@ - + Troubleshooting GPSD @@ -78,6 +78,7 @@ commands and section 8 to administrative commands.

  • Start at Boot Troubleshooting
  • Telnet
  • Udev Hotplug Troubleshooting
  • +
  • Systemd Troubleshooting
  • First Try

    @@ -472,6 +473,115 @@ matching expectations about the location of the control socket.

    If you do see these device file opens and closes logged, the udev end of the configuration is working.

    +

    Systemd Troubleshooting

    + +

    Systemd Interaction

    + +

    gpsd must be installed. We want gpsd itself and, for testing, the gpsd clients, at least cgps and possibly xgps.

    + +

    gpsd must running and reading from the GPS receiver. For general gpsd debugging, it is helpful to know that gpsd is running, and that the GPS receiver device file is present. For a u-blox receiver:

    + +
    root@orca:~# ps aux | grep -i gpsd | grep -v grep ; ls /dev/ttyA*
    +gpsd     14547  0.5  0.0  18092  3504 ?        S<sl 15:44   0:00 /usr/sbin/gpsd
    +/dev/ttyACM0
    +root@orca:~#
    + +

    (Devices file names vary. /dev/ttyU* is typical.)

    + +

    If gpsd isn't running, check other parts of this document, and INSTALL in the root of the git repo.

    + +

    The next question is, is gpsd controlled by systemd?

    + +

    Systemd isn't installed

    +

    Your problem lies elsewhere.

    + +

    Systemd is present but but does not manage gpsd.

    +

    You can use systemd's tools to check. systemctl status gpsd should tell you what systemd thinks gpsd's status is.

    + +
    +root@orca:~# systemctl status gpsd
    +● gpsd.service - GPS (Global Positioning System) Daemon
    +   Loaded: loaded (/lib/systemd/system/gpsd.service; enabled; vendor preset: enabled)
    +   Active: active (running) since Thu 2019-10-03 15:07:01 MDT; 1 weeks 2 days ago
    + Main PID: 32454 (gpsd)
    +    Tasks: 1 (limit: 4915)
    +   Memory: 924.0K
    +   CGroup: /system.slice/gpsd.service
    +           └─32454 /usr/sbin/gpsd
    +
    +Oct 03 15:07:01 orca systemd[1]: Starting GPS (Global Positioning System) Daemon...
    +Oct 03 15:07:01 orca systemd[1]: Started GPS (Global Positioning System) Daemon.
    +root@orca:~# 
    +
    + +

    This example shows that systemd clearly does control gpsd. If systemd replies something like Unit gpsd.service could not be found., systemd is present but does not control gpsd.

    + +

    Alternatively, see if any of the files gpsd.* are present under systemd's directories. That location is system dependent, but /lib/systemd/system/ is typical. Or use locate or your package manager to check.

    + +

    If systemd is present but does not control gpsd, your problem lies elsewhere.

    + +

    Systemd is present and controls gpsd

    + +

    Your tool for interacting with systemd is systemctl. The typical syntax is

    + +
    systemctl [OPTIONS...] COMMAND [UNIT...]
    + +

    For the gory details, see the systemctl man page. Generally useful commands include: daemon-reload, disable, enable, reload, restart, show, start, status, and stop. Note that daemon-reload and reload are not the same command. reload tells a unit to reload its configuration file (if it can do so). daemon-reload has systemd reload all unit files and its own configuration file.

    + +

    If you want to shut gpsd down, you have to shut down both units. Shutting down gpsd.service alone is not sufficient because gpsd.socket could fire it up again.

    + +
    systemctl stop gpsd.socket gpsd.service
    + +

    Note: issuing the stop command may not actually stop the service. On a Debian system out of the box, systemd starts gpsd up again.

    + +

    Real World Example

    + +

    For security, gpsd by default is shipped set up to listen only on the loopback interface, thereby restricting its audience to clients on the same computer. We'd like to allow other computers to listen in as well. This means:

    + + + +

    Once we know gpsd is running, we modify /etc/default/gpsd to provide the options we want. One to listen on all the interfaces (-G), and one to tell gpsd not to wait for a client to connect before polling (-n). The GPSD_OPTIONS stanza now looks like:

    + +
    +# Other options you want to pass to gpsd
    +# GPSD_OPTIONS=""
    +GPSD_OPTIONS="-Gn"
    +
    + +

    We can stop gpsd. Systemd will restart it for us, this time with the options in place. We then verify that the options are there:

    + +
    root@orca:~# systemctl stop gpsd.socket gpsd.service
    +root@orca:~# ps aux | grep -i gpsd | grep -v grep
    +gpsd     14547  0.5  0.0  18092  3504 ?        S<sl 15:44   0:00 /usr/sbin/gpsd -Gn
    +root@orca:~#
    + +

    But we aren't there yet. gpsd may be listening on all interfaces, but systemd's hold on the socket means gpsd can't hear anything on interfaces other than the loopback. We have to tell systemd to allow gpsd to hear other interfaces. We run systemctl edit --full gpsd.socket. Then we can edit it. After editing, the [Socket] stanza looks like so:

    + +
    +[Socket]
    +ListenStream=/var/run/gpsd.sock
    +ListenStream=[::1]:2947
    +# ListenStream=127.0.0.1:2947
    +ListenStream=0.0.0.0:2947
    +SocketMode=0600
    +
    + +

    When you are done editing, systemctl does what it needs to do internally to preserve your changes from being over-written during upgrades. It also does the equivalent of a systemctl daemon-reload for you.

    + +

    We now restart both gpsd units like so:

    + +
    systemctl restart gpsd.socket gpsd.service
    + +

    Now check with a local client, and a client on the remote computer:

    + +
    xgps <host>
    + +

    Where <host> in our example is orca. As usual, if you see data in the client, you're done.

    +