ademant
/
gpsd


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591
							<!DOCTYPE HTML>
<html lang="en">
<head lang="en">
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <meta name="Author" content="Eric S. Raymond">
   <meta name="Description" content="How to bring up a GPS under GPSD">
   <meta name="Keywords" content="GPS, gpsd, troubleshooting">
   <meta name="Revised" content="3 November 2019">
   <meta name="robots" content="index,follow">
   <title>Troubleshooting GPSD</title>
   <link rel="stylesheet" href="main.css" type="text/css">
</head>
<body>

<div id="Header">Troubleshooting GPSD</div>

<div id="Menu">
    <img src="gpsd-logo-small.png" alt="Small gpsd Logo" height="126"
    width="105"><br>
    <a href="index.html">Home</a><br>
    <a href="index.html#news">News</a><br>
    <a href="index.html#downloads">Downloads</a><br>
    <a href="index.html#mailing-lists">Mailing lists</a><br>
    <a href="index.html#documentation">Documentation</a><br>
    <a href="faq.html">FAQ</a><br>
    <a href="xgps-sample.html">Screenshots</a><br>
    <a href="index.html#recipes">Recipes</a><br>
    <a href="index.html#others">Other GPSDs</a><br>
    <a href="hardware.html">Hardware</a><br>
    <a href="for-vendors.html">For GPS Vendors</a><br>
    <a href="wishlist.html">Wish List</a><br>
    <a href="hall-of-shame.html">Hall of Shame</a><br>
    Troubleshooting<br>
    <a href="hacking.html">Hacker's Guide</a><br>
    <a href="protocol-transition.html">Application Compatibility</a>
    <a href="references.html">References</a><br>
    <a href="history.html">History</a><br>
    <a href="future.html">Future</a><br>

    <div>&nbsp;</div>

    <a href='http://www.catb.org/hacker-emblem/'><img
    src='glider.png' alt='hacker emblem' height="55" width="55"></a><br>

    <script src="https://www.openhub.net/p/3944/widgets/project_thin_badge.js"></script>

    <hr>
    <script><!--
    google_ad_client = "pub-1458586455084261";
    google_ad_width = 160;
    google_ad_height = 600;
    google_ad_format = "160x600_as";
    google_ad_type = "text";
    google_ad_channel = "";
    //--></script>
    <script src="https://pagead2.googlesyndication.com/pagead/show_ads.js">
    </script>
    <hr>

    <a href="https://validator.w3.org/check/referer"><img
          src="https://www.w3.org/Icons/valid-html401"
          alt="Valid HTML 4.01!" height="31" width="88"></a>
</div>
<div id="Content">

<h1>Contents</h1>

<p>References like <b>foobar(n)</b> are a Unix convention meaning you
should look up the program <b>foobar</b> using the <b>man</b> utility
for browsing manual pages. Numeric section 1 refers to general
commands and section 8 to administrative commands.</p>

<ol class="ToC">
  <li><a href="#firsttry">First Try</a></li>
  <li><a href="#gpstroubleshooting">GPS Troubleshooting</a></li>
  <li><a href="#usbtroubleshooting">USB Troubleshooting</a></li>
  <li><a href="#generaltroubleshooting">General Troubleshooting</a></li>
  <li><a href="#startuptroubleshooting">Start at Boot Troubleshooting</a></li>
  <li><a href="#telnet" >Telnet</a></li>
  <li><a href="#hotplugtroubleshooting">Udev Hotplug Troubleshooting</a></li>
  <li><a href="#systemdtroubleshooting" >Systemd Troubleshooting</a></li>
</ol>

<h1 id='firsttry'>First Try</h1>

<p>If you have a USB GPS and have installed from a binary package,
plug your GPS into a USB port and run <code>xgps</code> or
<code>cgps</code>.  Very likely you will see fix data appear in the
client.  If so, you're done.</p>

<p>If you have a Bluetooth GPS, follow our <a href="bt.html">Bluetooth
instructions</a> and run <code>xgps</code> or <code>cgps</code>.  Very
likely you will see fix data appear in the client.  If so, you're
done.</p>

<p>If you have a serial (RS232) GPS, plug it into a serial port
connector and jump to <a href="#generaltroubleshooting">General
Troubleshooting</a></p>

<p>We do not yet have troubleshooting instructions for GPSes using
CF (Compact Flash) interfaces. Please contribute some if you can.</p>

<p>If your test client does not show data, keep reading.</p>

<h1 id='gpstroubleshooting'>GPS troubleshooting</h1>

<p>Check that the GPS has power. If it is a USB device, it
needs to be cabled to a USB port to have power. All Bluetooth GPSes
and some serial GPSes are powered by an on-board battery; check that
the battery is present and charged. The GPS may have an on-off switch
which needs to be in the 'on' position.</p>

<p>Most GPSes have a power-on LED; it should be continuously on
or blinking once a second. If it is continuously off, your GPS is dead
or disconnected. Check that it has power.</p>

<h1 id='usbtroubleshooting'>USB troubleshooting</h1>

<p>USB GPSes actually emulate RS232 serial using converter chips.
Under Linux, the <code>usbserial</code> kernel module must be loaded
for correct operation of this class of device. Normally this module
load should happen automatically when the device activates, but if you
don't receive data check for it with <b>lsmod(8)</b>.</p>

<p>On Linux systems with module autoloading disabled or misconfigured,
it is possible you may need to load the module manually with a command,
while running as root, such as <code>modprobe usbserial vendor=0x1a86
product=0x7523</code>.  Do not copy those hex numbers slavishly, they
are examples.  To get the right numbers, you will need to dig up the
vendor and product ID of your USB-serial converter device.</p>

<p>Run <b>lsusb(8)</b> before and after connecting your GPS; after,
you should see an additional line indicating a new device.  Expect the
new line to describe a serial-to-USB adapter chip, often (but not
always) the Prolific Technology PL2303.  Then run <b>dmesg(8)</b>,
looking near the end for a message indicating a new USB device of
that kind and giving you the device path - <code>/dev/ttyUSBn</code>
for some number n.</p>

<p>If you have installed a GPSD binary package on a Linux system and
are using a USB GPS, you should not need to start gpsd manually,
because the hotplug system will have done it for you.  You should be
able to start a test client (such as <code>cgps</code> or
<code>xgps</code>) and watch it report fixes.  If this works, you are
done and can skip the rest of this guide.</p>

<h1 id="generaltroubleshooting">General Troubleshooting</h1>

<h2>Make sure gpsd is not running</h2>

<p>Before doing anything else, make sure there is no instance of gpsd
running, as root, do:</p>

<pre># killall gpsd
# killall -9 gpsd</pre>

<p>Remove any sockets gpsd might have left behind, as root, do:</p>

<pre># rm @RUNDIR@/gpsd.sock</pre>

<h2>Ensure no other programs are using your device</h2>
<p>Tools like modemmanager might be using your device, probably
automatically attached to it by udev or systemd. To check if your
device is ready to be used by gpsd try running <b>lsof(8)</b>
and search the output for your GPS device path (for example
<code>lsof -n | grep /dev/ttyUSB0</code>). If something is
listed in the output you'll have to stop these processes and
reconfigure them to ignore your GPS device.

<h2>Use gpsmon to check that your device is emitting data</h2>

<p>Try running <b>gpsmon(1)</b>, giving it your GPS device path as an
argument (for example. <code>"gpsmon /dev/ttyUSB0"</code>). After a
few moments to sync up, it should display a screen full of data on the
device, including displaying the raw packet data streaming from it.</p>

<p>If <b>gpsmon(1)</b> reports no data at all, you may have the device
path wrong; check that using <b>dmesg(8)</b> or by whatever means you
have available.  If you have the right device, you may have some
low-level system problem with serial or USB that you'll need to fix
before <code>gpsd</code> will operate. Check your cabling, power, and
kernel configuration.</p>

<h2>Launch gpsd to see its progress messages</h2>

<p>You can launch gpsd with the options -N (don't daemonize) and -D
[0-8] (debug and level). This will let it run and send output,
including traffic from the GPS receiver, to the terminal. This is a
recommended first step because it avoids client issues. For example,
here we give gpsd a control socket but no device:</p>

<pre># gpsd -N -D3 -F @RUNDIR/gpsd.sock
gpsd: launching (Version 2.96~dev)
gpsd: listening on port gpsd
gpsd: running with effective group ID 0
gpsd: running with effective user ID 0
^Cgpsd: received terminating signal 2.
gpsd: exiting.
#</pre>

<p>If you get something like this error message: "gpsd: error while
loading shared libraries: libgpsd.so.0: cannot open shared object
file: No such file or directory" then run ldconfig(8) and try again.</p>

<p>Here we give it a device file. But the device file isn't there, and
there is no receiver.</p>

<pre># gpsd -N -D3 -F @RUNDIR/gpsd.sock /dev/ttyUSB0
gpsd: launching (Version 2.96~dev)
gpsd: listening on port gpsd
gpsd: running with effective group ID 0
gpsd: running with effective user ID 0
gpsd: stashing device /dev/ttyUSB0 at slot 0
^Cgpsd: received terminating signal 2.
gpsd: exiting.
#</pre>

<p>This time, gpsd stashes the device file and waits for some outside
agency, like udev, to create it. Like so:</p>

<pre># gpsd -N -D3 -F @RUNDIR/gpsd.sock /dev/ttyUSB0
gpsd: launching (Version 2.96~dev)
gpsd: listening on port gpsd
gpsd: running with effective group ID 0
gpsd: running with effective user ID 0
gpsd: stashing device /dev/ttyUSB0 at slot 0
gpsd: control socket connect on fd 6
gpsd: &lt;= control(6): /dev/ttyUSB0 already active
^Cgpsd: received terminating signal 2.
gpsd: exiting.
#</pre>

<p>If you have udev on your computer, and you don't see gpsd notice
the device (&quot;control socket connect on fd 6&quot;), check to be
sure <a href="#hotplugtroubleshooting">udev is working correctly</a>.</p>

<p>If you pull the plug on the receiver, gpsd will note the change.</p>

<p>With the receiver plugged in and gpsd running as above, you can
launch a client. <code>xgps</code> comes with the distribution.
On some Linuxes, it may be in a separate package, e.g. gpsd-clients.
You should then see a lot of traffic between gpsd and the client in
the gpsd terminal window. For example, here's a fix as reported by
gpsd:</p>

<pre>gpsd: SiRF: MND 0x02: time=1293859466.85 lat=42.64 lon=-118.21 alt=1315.15 track=0.00 speed=0.00 mode=1 status=0 hdop=0.00 used=0 mask={TIME|LATLON|ALTITUDE|SPEED|TRACK|STATUS|MODE|DOP|USED}</pre>

<p>Note that gpsd doesn't try to activate the receiver until it has a
client, and the client asks for data with a ?WATCH request. It also
shuts down its connection to the receiver when it has no clients. This
is a power saving feature.</p>

<p>Another way to verify that gpsd can open the device file is with
lsof(8) (&quot;list open files&quot;):</p>

<pre># lsof | grep ttyU
gpsd      20895     nobody    7u      CHR      188,0      0t0     851138 /dev/ttyUSB0
#</pre>

<h1 id="startuptroubleshooting">Troubleshooting Start at Boot</h1>

<p>If gpsd launches at boot, you should be able to start it up or shut
it down with one of the many utilities that manipulate system-V like
startup environments, e.g. service(8). <code>service gpsd
start</code>, etc. works on some Linuxes. sysv-rc-conf(8) is a handy
curses utility for the job. Watch the output.</p>

<p>You can also look at your boot messages with dmesg(1).</p>

<h2>Ubuntu/Debian</h2>

<p>The .deb package supplied for the Debian and Ubuntu Linux
distributions launch at boot either using systemd with gpsd.socket
and gpsd.service, or on older releases from the system V-like script
<code>/etc/init.d/gpsd</code>. However, both are governed by a control
file, <code>/etc/default/gpsd</code>. If necessary, edit the control
file as root.</p>

<p>Please note that systemd will only start gpsd on request
by clients connecting to the unix or tcp socket. In case you need
gpsd to run always, you'll need to configure systemd to start it.
One way would be to create <code>/etc/systemd/system/gpsd.service</code>
with the following content:
</p>
<pre>
[Unit]
Description=GPS (Global Positioning System) Daemon
Requires=gpsd.socket
# Needed with chrony SOCK refclock
After=chronyd.service

[Service]
EnvironmentFile=-/etc/default/gpsd
EnvironmentFile=-/etc/sysconfig/gpsd
ExecStart=/usr/sbin/gpsd -N $GPSD_OPTIONS $DEVICES

[Install]
WantedBy=multi-user.target
Also=gpsd.socket
</pre>
<p>
To ask systemd to reload its config run
<code>systemctl daemon-reload; systemctl reenable gpsd.service</code>.
Instead of using the EnvironmentFile(s) you could just edit the command
line as necessary for your system. Don't forget to run
<code>systemctl daemon-reload</code> after changing the file.
</p>

<p>You will likely want the gpsd-clients package as a debugging
tool. These are the clients maintained as part of the gpsd
project. Other clients may or may not use the right libgpsd or the
right protocol, or something. So make sure gpsd is working correctly
with the gpsd clients. You can always purge them later.</p>

<p>In case you need to debug the gpsd or its clients using gdb or
the python debugger the gpsd-dbg package is provided. It should
contain all necessary debug symbols to create useful backtraces.</p>

<p>If you have a prior installation of gpsd from a deb package, and
are switching to compiling your own, from a recent tarball or from the
git repository, it is not enough to <code>apt-get remove</code> the
prior installation. You must <code>apt-get purge</code> them. This
removes some configuration files left behind by remove.</p>

<p>If you do compile your own gpsd, be aware that installing gpsd
client packages can force installation of gpsd as well. This can also
happen on debian systems when apt is set up to install recommended
packages as dependencies.</p>

<p>One culprit is packages like
<a href="http://www.tangogps.org/">tangogps</a>, which recommendd gpsd.
Fortunately, since it recommends gpsd, you can install it using
<code>apt-get install --no-install-recommends</code> or disable the
installation of recommended packages permanently. Put the following in
a file with a high leading number in <code>/etc/apt/apt.conf.d</code>,
e.g. <code>90no.recommendations</code>:</p>

<pre>APT::Install-Recommends &quot;false&quot;;
</pre>

<p>Other client packages may not be so lenient, but you can use the
tool <b>equivs</b> to create an empty fake package which provides
gpsd.</p>

<h2>Red Hat</h2>

<p>The rpm package made from the gpsd distribution will launch at boot
from the script <code>/etc/init/rc.d/gpsd</code>. It is governed by
the file <code>/etc/sysconfig/gpsd</code>, although it it doesn't find
that file, it will provide its own defaults.</p>

<p>You will likely want the gpsd-clients package as a debugging
tool. These are the clients maintained by the gpsd developers. Other
clients may or may not use the right libgpsd or the right protocol, or
something. So make sure gpsd is working correctly with the gpsd
clients. You can always purge them later.</p>

<h1 id="telnet">Telnet</h1>

<p>Telnet provides a quick and dirty acceptance test for gpsd. Other
clients (<code>cgps</code>, <code>xgps</code>, and other)
are preferable, so consider telnet a last ditch tool. You can telnet
into gpsd:</p>

<pre>$ telnet localhost 2947
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{&quot;class&quot;:&quot;VERSION&quot;,&quot;release&quot;:&quot;2.96~dev&quot;,&quot;rev&quot;:&quot;2011-03-15T03:05:33&quot;,&quot;proto_major&quot;:3,&quot;proto_minor&quot;:4}
</pre>

<p>Note that the <code>release</code> strings will be different in
your case.</p>

<p>To see data from the receiver in JSON (if any), enter the command
<samp>?WATCH={&quot;enable&quot;:true,&quot;json&quot;:true}</samp>. To
end JSON output, <samp>?WATCH={&quot;enable&quot;:false}</samp>. Then
control-] and &quot;exit&quot; to exit the telnet client.</p>

<p>For more information, see <a
href="client-howto.html#_how_the_gpsd_wire_protocol_works" >How the
GPSD wire protocol works</a> in the <a href="client-howto.html" >GPSD
Client HOWTO</a>.</p>

<h1 id="hotplugtroubleshooting">Udev Hotplug Troubleshooting</h1>

<p>The Linux udev system has been prone to change out from under us,
breaking our hotplug support for USB receivers.  Accordingly, here's a
short guide to verifying that the different pieces are working
correctly, with indications of where to troubleshoot on failure.</p>

<p>First, verify that your USB subsystem can see your receiver.  Run
lsusb(1).  Plug the receiver in and run lsusb(1) again, looking for
the extra line - it will be identified by a serial-to-USB converter
chip type such as a PL2303. Unplug the receiver and verify that the
line describing the device is gone.</p>

<p>If this test fails, something very basic is wrong at hardware
level.  If your receiver has a two-section cable joined by something
like a <a
href="https://en.wikipedia.org/wiki/Mini-DIN_connector">6-pin
mini-DIN connector</a>, with a component housing between that and the
USB plug, be aware that the serial converter may live in that housing
and you have to unplug the <b>entire cable</b> from your computer, not
just separate the halves of the mini-DIN connector. If there is no
such joint, it may be that your receiver is defective or dead. See
your vendor documentation for help in diagnosis. The least likely
failure is for the USB hardware on the PC side to be buggy.</p>

<p>The next thing to try is watching the hotplug events in your system
logs.  Do <code>tail -f /var/log/syslog</code>; plug in and unplug the
receiver.  You should see messages indicating from the USB subsystem
in the kernel indicating device connect and disconnect.  If you don't,
check your kernel configuration; USB support may be absent or
misconfigured.</p>

<p>Now we involve the udev system.  Unplug the receiver.  If you are
compiling gpsd, run <code>make udev-install</code> from the source
directory to install the required udev rules.  (There is a <code>make
udev-uninstall</code> for cleaning up after this test.)  If you are
using a package, your package manager will install these files for
you.  Do <code>tail -f /var/log/syslog</code>.  Now plug in the
receiver.</p>

<p>You should see messages that include something like the following
text (the USB device may vary):</p>

<pre>
gpsd.hotplug: gpsd_control(action=add, arg=/dev/ttyUSB0)
gpsd.hotplug: launching gpsd  -F @RUNDIR/gpsd.sock
</pre>

<p>These are from the gpsd.hotplug handler called by udev on a hotplug
event matching one of the known udev types for a USB GPS, and indicating
the launch of a gpsd instance.</p>

<p>If you don't see this, several things could be going wrong. The
udev rules may not be installed correctly. Or the handler they call
may be unable to run for some reason; it has two layers, a shell script
wrapper around a little Python program that does the real work.  You
may have to figure out where the udev log messages go on your system
and use udevadm(8) to crank up the log level until you can see what's
going on.</p>

<p>If your GPS uses an unusual serial-to-USB converter, the GPSD rules
may not recognize it as a probable GPS. You'll need to look at the
converter type indicated in the lsusb(1) listing and match it against
the rules in the gpsd.rules file. If it's not known, please report
this as a bug to the GPSD developers.</p>

<p>Once you know that udev can launch gpsd, you'll want to watch what
it's doing with the hotplug notifications. Unplug the receiver and
kill the running gpsd instance, if there is one. Now run <code>make
udev-test</code> and plug in the receiver. (For those using packages,
this is the equivalent of &quot;<code>gpsd -N -n -F @RUNDIR/gpsd.sock
-D 5</code>&quot;.) </p>

<p>You can also launch the hotplug code manually: <code>cd /lib/udev
&amp;&amp; ./gpsd.hotplug add /dev/ttyUSB0</code> If this fails, there is
something wrong with the hotplug code. If it succeeds, the problem may
be in how udev is calling gpsd.hotplug, or udev may never call
gpsd.hotplug.</p>

<p>You should see log messages from gpsd indicating that the control
socket has received a command to add the device, and then data
from the device.  When you unplug and replug the device, gpsd
should emit messages about the device closes and opens.</p>

<p>If you don't see this, there's a bug or misconfiguration
somewhere. Check to make sure the hotplug handler and gpsd have
matching expectations about the location of the control socket.</p>

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

<h1 id="systemdtroubleshooting">Systemd Troubleshooting</h1>

<h2>Systemd Interaction</h2>

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

<p>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:</p>

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

<p>(Devices file names vary. <code>/dev/ttyU*</code> is typical.)</p>

<p>If gpsd isn't running, check other parts of this document, and <a href="https://gitlab.com/gpsd/gpsd/blob/master/INSTALL" >INSTALL</a> in the root of the <a href="https://gitlab.com/gpsd/gpsd" >git repo</a>.</p>

<p>The next question is, is gpsd controlled by systemd?</p>

<h3>Systemd isn't installed</h3>
<p>Your problem lies elsewhere.</p>

<h3>Systemd is present but but does not manage gpsd.</h3>
<p>You can use systemd's tools to check. <code><a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#status%20PATTERN%E2%80%A6%7CPID%E2%80%A6%5D" >systemctl status</a> gpsd</code> should tell you what systemd thinks gpsd's status is.</p>

<pre>
root@orca:~# <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#status%20PATTERN%E2%80%A6%7CPID%E2%80%A6%5D" >systemctl status</a> 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:~# 
</pre>

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

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

<p>If systemd is present but does not control gpsd, your problem lies elsewhere.</p>

<h3>Systemd is present and controls gpsd</h3>

<p>Your tool for interacting with systemd is <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html" >systemctl</a>. The typical syntax is</p>

<pre>systemctl [OPTIONS...] COMMAND [UNIT...]</pre>

<p>For the gory details, see the <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html" >systemctl man page</a>. Generally useful commands include: <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#daemon-reload" >daemon-reload</a>, <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#disable%20UNIT%E2%80%A6" >disable</a>, <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#enable%20UNIT%E2%80%A6" >enable</a>, <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#reload%20PATTERN%E2%80%A6" >reload</a>, <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#restart%20PATTERN%E2%80%A6" >restart</a>, <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#show%20PATTERN%E2%80%A6%7CJOB%E2%80%A6" >show</a>, <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#start%20PATTERN%E2%80%A6" >start</a>, <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#status%20PATTERN%E2%80%A6%7CPID%E2%80%A6%5D" >status</a>, and <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#stop%20PATTERN%E2%80%A6" >stop</a>. 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.</p>

<p>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.</p>

<pre><a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#stop%20PATTERN%E2%80%A6" >systemctl stop</a> gpsd.socket gpsd.service</pre>

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

<h2>Real World Example</h2>

<p>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:</p>

<ul>
  <li>Opening the firewall at the gpsd assigned port, 2947. That is beyond the scope of this document.</li>
  <li>Adding the appropriate switch to the command line for gpsd. While we're at it, we'll also add the -n switch.</li>
  <li>Changing the gpsd.socket unit so that other clients can connect to the daemon.</li>
</ul>

<p>Once we know gpsd is running, we modify <code>/etc/default/gpsd</code> 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:</p>

<pre>
# Other options you want to pass to gpsd
# GPSD_OPTIONS=""
GPSD_OPTIONS="-Gn"
</pre>

<p>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:</p>

<pre>root@orca:~# <a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#stop%20PATTERN%E2%80%A6" >systemctl stop</a> gpsd.socket gpsd.service
root@orca:~# ps aux | grep -i gpsd | grep -v grep
gpsd     14547  0.5  0.0  18092  3504 ?        S&lt;sl 15:44   0:00 /usr/sbin/gpsd -Gn
root@orca:~#</pre>

<p>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 <code><a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#edit%20UNIT%E2%80%A6" >systemctl edit --full gpsd.socket</a></code>. Then we can edit it. After editing, the [Socket] stanza looks like so:</p>

<pre>
[Socket]
ListenStream=@RUNDIR/gpsd.sock
ListenStream=[::1]:2947
# ListenStream=127.0.0.1:2947
ListenStream=0.0.0.0:2947
SocketMode=0600
</pre>

<p>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 <code>systemctl daemon-reload</code> for you.</p>

<p>We now restart both gpsd units like so:</p>

<pre><a href="https://www.freedesktop.org/software/systemd/man/systemctl.html#restart%20PATTERN%E2%80%A6" >systemctl restart</a> gpsd.socket gpsd.service</pre>

<p>Now check with a local client, and a client on the remote computer:</p>

<pre>xgps &lt;host&gt;</pre>

<p>Where &lt;host&gt; in our example is orca. As usual, if you see data in the client, you're done.</p>

<hr>
<script src="datestamp.js"></script>
</div>
</body>
</html>