dirmngr

title: dirmngr(8)

summary: GnuPG's network access daemon

text:
# dirmngr(8)

## NAME
dirmngr - GnuPG's network access daemon

## SYNOPSIS
dirmngr [options] command [args]

## DESCRIPTION
Since version 2.1 of GnuPG, dirmngr takes care of accessing the OpenPGP keyservers. As with previous versions it is also used as a server for managing and downloading certificate revocation lists (CRLs) for X.509 certificates, downloading X.509 certificates, and providing access to OCSP providers. Dirmngr is invoked internally by gpg, gpgsm, or via the gpg-connect-agent tool.

## COMMANDS
Commands are not distinguished from options except for the fact that only one command is allowed.

--version

Print the program version and licensing information. Note that you cannot abbreviate this command.

--help, -h

Print a usage message summarizing the most useful command-line options. Note that you cannot abbreviate this command.

--dump-options

Print a list of all available options and commands. Note that you cannot abbreviate this command.

--server

Run in server mode and wait for commands on the stdin. The default mode is to create a socket and listen for commands there. This is only used for testing.

--daemon

Run in background daemon mode and listen for commands on a socket. This is the way dirmngr is started on demand by the other GnuPG components. To force starting dirmngr it is in general best to use gpgconf --launch dirmngr.

--supervised

Run in the foreground, sending logs to stderr, and listening on file descriptor 3, which must already be bound to a listening socket. This option is deprecated and not supported on Windows.

--list-crls

List the contents of the CRL cache on stdout. This is probably only useful for debugging purposes.

--load-crl file

This command requires a filename as additional argument, and it will make Dirmngr try to import the CRL in file into it's cache. Note, that this is only possible if Dirmngr is able to retrieve the CA's certificate directly by its own means. In general it is better to use gpgsm's --call-dirmngr loadcrl filename command so that gpgsm can help dirmngr.

--fetch-crl url

This command requires an URL as additional argument, and it will make dirmngr try to retrieve and import the CRL from that url into it's cache. This is mainly useful for debugging purposes. The dirmngr-client provides the same feature for a running dirmngr.

--shutdown

This commands shuts down an running instance of Dirmngr. This command has currently no effect.

--flush

This command removes all CRLs from Dirmngr's cache. Client requests will thus trigger reading of fresh CRLs.

## OPTIONS
Note that all long options with the exception of --options and --homedir may also be given in the configuration file after stripping off the two leading dashes.

--options file

Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘dirmngr.conf’ and expected in the home directory.

--homedir dir

Set the name of the home directory to dir. This option is only effective when used on the command line. The default is the directory named ‘.gnupg’ directly below the home directory of the user unless the environment variable GNUPGHOME has been set in which case its value will be used. Many kinds of data are stored within this directory.

-v

--verbose

Outputs additional information while running. You can increase the verbosity by giving several verbose commands to dirmngr, such as -vv.

--log-file file

Append all logging output to file. This is very helpful in seeing what the agent actually does. Use ‘socket://’ to log to socket.

--compatibility-flags flags

Set compatibility flags to work around certain problems or to emulate bugs. The flags are given as a comma separated list of flag names and are OR-ed together. The special flag "none" clears the list and allows to start over with an empty list. To get a list of available flags the sole word "help" can be used.

--debug-level level

Select the debug level for investigating problems. level may be a numeric value or by a keyword:

none

No debugging at all. A value of less than 1 may be used instead of the keyword.

basic

Some basic debug messages. A value between 1 and 2 may be used instead of the keyword.

advanced

More verbose debug messages. A value between 3 and 5 may be used instead of the keyword.

expert

Even more detailed messages. A value between 6 and 8 may be used instead of the keyword.

guru

All of the debug messages you can get. A value greater than 8 may be used instead of the keyword. The creation of hash tracing files is only enabled if the keyword is used.

How these messages are mapped to the actual debugging flags is not specified and may change with newer releases of this program. They are however carefully selected to best aid in debugging.

--debug flags

Set debug flags. All flags are or-ed and flags may be given in C syntax (e.g. 0x0042) or as a comma separated list of flag names. To get a list of all supported flags the single word "help" can be used. This option is only useful for debugging and the behavior may change at any time without notice.

--debug-all

Same as --debug=0xffffffff

--tls-debug level

Enable debugging of the TLS layer at level. The details of the debug level depend on the used TLS library and are not set in stone.

--debug-wait n

When running in server mode, wait n seconds before entering the actual processing loop and print the pid. This gives time to attach a debugger.

--disable-check-own-socket

On some platforms dirmngr is able to detect the removal of its socket file and shutdown itself. This option disable this self-test for debugging purposes.

-s

--sh

-c

--csh

Format the info output in daemon mode for use with the standard Bourne shell respective the C-shell. The default is to guess it based on the environment variable SHELL which is in almost all cases sufficient.

--force

Enabling this option forces loading of expired CRLs; this is only useful for debugging.

--use-tor

--no-use-tor

The option --use-tor switches Dirmngr and thus GnuPG into ``Tor mode'' to route all network access via Tor (an anonymity network). Certain other features are disabled in this mode. The effect of --use-tor cannot be overridden by any other command or even by reloading dirmngr. The use of --no-use-tor disables the use of Tor. The default is to use Tor if it is available on startup or after reloading dirmngr. The test on the availability of Tor is done by trying to connect to a SOCKS proxy at either port 9050 or 9150; if another type of proxy is listening on one of these ports, you should use --no-use-tor.

--standard-resolver

This option forces the use of the system's standard DNS resolver code. This is mainly used for debugging. Note that on Windows a standard resolver is not used and all DNS access will return the error ``Not Implemented'' if this option is used. Using this together with enabled Tor mode returns the error ``Not Enabled''.

--recursive-resolver

When possible use a recursive resolver instead of a stub resolver.

--resolver-timeout n

Set the timeout for the DNS resolver to N seconds. The default are 30 seconds.

--connect-timeout n

--connect-quick-timeout n

Set the timeout for HTTP and generic TCP connection attempts to N seconds. The value set with the quick variant is used when the --quick option has been given to certain Assuan commands. The quick value is capped at the value of the regular connect timeout. The default values are 15 and 2 seconds. Note that the timeout values are for each connection attempt; the connection code will attempt to connect all addresses listed for a server.

--listen-backlog n

Set the size of the queue for pending connections. The default is 64.

--allow-version-check

Allow Dirmngr to connect to https://versions.gnupg.org to get the list of current software versions. If this option is enabled the list is retrieved in case the local copy does not exist or is older than 5 to 7 days. See the option --query-swdb of the command gpgconf for more details. Note, that regardless of this option a version check can always be triggered using this command:

```
       gpg-connect-agent --dirmngr 'loadswdb --force' /bye
```

--keyserver name

Use name as your keyserver. This is the server that gpg communicates with to receive keys, send keys, and search for keys. The format of the name is a URI: `scheme:[//]keyservername[:port]' The scheme is the type of keyserver: "hkp" for the HTTP (or compatible) keyservers or "ldap" for the LDAP keyservers. Note that your particular installation of GnuPG may have other keyserver types available as well. Keyserver schemes are case-insensitive. After the keyserver name, optional keyserver configuration options may be provided. These are the same as the --keyserver-options of gpg, but apply only to this particular keyserver. Some keyservers synchronize with each other, so there is not always a need to send keys to more than one server. Some keyservers use round robin DNS to give a different keyserver each time you use it.

If exactly two keyservers are configured and only one is a Tor hidden service (.onion), Dirmngr selects the keyserver to use depending on whether Tor is locally running or not. The check for a running Tor is done for each new connection.

If no keyserver is explicitly configured, dirmngr will use the built-in default of https://keyserver.ubuntu.com.

Windows users with a keyserver running on their Active Directory may use the short form ldap:/// for name to access this directory.

For accessing anonymous LDAP keyservers name is in general just a ldaps://ldap.example.com. A BaseDN parameter should never be specified. If authentication is required things are more complicated and two methods are available:

The modern method (since version 2.2.28) is to use the very same syntax as used with the option --ldapserver. Please see over there for details; here is an example:

```
       keyserver ldap:ldap.example.com::uid=USERNAME,ou=GnuPG Users,

       dc=example,dc=com:PASSWORD::starttls
```

The other method is to use a full URL for name; for example:

```
       keyserver ldaps://ldap.example.com/????bindname=uid=USERNAME

       %2Cou=GnuPG%20Users%2Cdc=example%2Cdc=com,password=PASSWORD
```

Put this all on one line without any spaces and keep the '%2C'

as given. Replace USERNAME, PASSWORD, and the 'dc' parts

according to the instructions received from your LDAP

administrator. Note that only simple authentication

(i.e. cleartext passwords) is supported and thus using ldaps is

strongly suggested (since 2.2.28 "ldaps" defaults to port 389

and uses STARTTLS). On Windows authentication via AD can be

requested by adding gpgNtds=1 after the fourth question

mark instead of the bindname and password parameter.

--nameserver ipaddr

In ``Tor mode'' Dirmngr uses a public resolver via Tor to resolve DNS names. If the default public resolver, which is 8.8.8.8, shall not be used a different one can be given using this option. Note that a numerical IP address must be given (IPv6 or IPv4) and that no error checking is done for ipaddr.

--disable-ipv4

--disable-ipv6

Disable the use of all IPv4 or IPv6 addresses.

--disable-ldap

Entirely disables the use of LDAP.

--disable-http

Entirely disables the use of HTTP.

--ignore-http-dp

When looking for the location of a CRL, the to be tested certificate usually contains so called CRL Distribution Point (DP) entries which are URLs describing the way to access the CRL. The first found DP entry is used. With this option all entries using the HTTP scheme are ignored when looking for a suitable DP.

--ignore-ldap-dp

This is similar to --ignore-http-dp but ignores entries using the LDAP scheme. Both options may be combined resulting in ignoring DPs entirely.

--ignore-ocsp-service-url

Ignore all OCSP URLs contained in the certificate. The effect is to force the use of the default responder.

--honor-http-proxy

If the environment variable ‘http_proxy’ has been set, use its value to access HTTP servers.

--http-proxy host[:port]

Use host and port to access HTTP servers. The use of this option overrides the environment variable ‘http_proxy’ regardless whether --honor-http-proxy has been set.

--ldap-proxy host[:port]

Use host and port to connect to LDAP servers. If port is omitted, port 389 (standard LDAP port) is used. This overrides any specified host and port part in a LDAP URL and will also be used if host and port have been omitted from the URL.

--only-ldap-proxy

Never use anything else but the LDAP "proxy" as configured with --ldap-proxy. Usually dirmngr tries to use other configured LDAP server if the connection using the "proxy" failed.

--ldapserverlist-file file

Read the list of LDAP servers to consult for CRLs and X.509 certificates from file instead of the default per-user ldap server list file. The default value for file is ‘dirmngr_ldapservers.conf’. This server list file contains one LDAP server per line in the format

hostname:port:username:password:base_dn:flags

Lines starting with a ‘#’ are comments.

Note that as usual all strings entered are expected to be UTF-8 encoded. Obviously this will lead to problems if the password has originally been encoded as Latin-1. There is no other solution here than to put such a password in the binary encoding into the file (i.e. non-ascii characters won't show up readable). ([The gpgconf tool might be helpful for frontends as it enables editing this configuration file using percent-escaped strings.])

--ldapserver spec

This is an alternative way to specify LDAP servers for CRL and X.509 certificate retrieval. If this option is used the servers configured in ‘dirmngr_ldapservers.conf’ (or the file given by --ldapserverlist-file) are cleared. Note that ‘dirmngr_ldapservers.conf’ is not read again by a reload signal. However, --ldapserver options are read again. spec is either a proper LDAP URL or a colon delimited list of the form

hostname:port:username:password:base_dn:flags:

with an optional prefix of ldap: (but without the two slashes which would turn this into a proper LDAP URL). flags is a list of one or more comma delimited keywords:

plain

The default: Do not use a TLS secured connection at all; the default port is 389.

starttls

Use STARTTLS to secure the connection; the default port is 389.

ldaptls

Tunnel LDAP through a TLS connection; the default port is 636.

ntds

On Windows authenticate the LDAP connection using the Active Directory with the current user.

areconly

On Windows use only the A or AAAA record when resolving the LDAP server name.

Note that in an URL style specification the scheme ldaps:// refers to STARTTLS and _not_ to LDAP-over-TLS.

--ldaptimeout secs

Specify the number of seconds to wait for an LDAP query before timing out. The default are 15 seconds. 0 will never timeout.

--add-servers

This option makes dirmngr add any servers it discovers when validating certificates against CRLs to the internal list of servers to consult for certificates and CRLs. This option should in general not be used. This option might be useful when trying to validate a certificate that has a CRL distribution point that points to a server that is not already listed in the ldapserverlist. Dirmngr will always go to this server and try to download the CRL, but chances are high that the certificate used to sign the CRL is located on the same server. So if dirmngr doesn't add that new server to list, it will often not be able to verify the signature of the CRL unless the --add-servers option is used.

Caveat emptor: Using this option may enable denial-of-service attacks and leak search requests to unknown third parties. This is because arbitrary servers are added to the internal list of LDAP servers which in turn is used for all unspecific LDAP queries as well as a fallback for queries which did not return a result.

--allow-ocsp

This option enables OCSP support if requested by the client. OCSP requests are rejected by default because they may violate the privacy of the user; for example it is possible to track the time when a user is reading a mail.

--ocsp-responder url

Use url as the default OCSP Responder if the certificate does not contain information about an assigned responder. Note, that --ocsp-signer must also be set to a valid certificate.

--ocsp-signer fpr|file

Use the certificate with the fingerprint fpr to check the responses of the default OCSP Responder. Alternatively a filename can be given in which case the response is expected to be signed by one of the certificates described in that file. Any argument which contains a slash, dot or tilde is considered a filename. Usual filename expansion takes place: A tilde at the start followed by a slash is replaced by the content of ‘HOME’, no slash at start describes a relative filename which will be searched at the home directory. To make sure that the file is searched in the home directory, either prepend the name with "./" or use a name which contains a dot. If a response has been signed by a certificate described by these fingerprints no further check upon the validity of this certificate is done.

The format of the FILE is a list of SHA-1 fingerprint, one per line with optional colons between the bytes. Empty lines and lines prefix with a hash mark are ignored.

--ocsp-max-clock-skew n

The number of seconds a skew between the OCSP responder and them local clock is accepted. Default is 600 (10 minutes).

--ocsp-max-period n

Seconds a response is at maximum considered valid after the time given in the thisUpdate field. Default is 7776000 (90 days).

--ocsp-current-period n

The number of seconds an OCSP response is considered valid after the time given in the NEXT_UPDATE datum. Default is 10800 (3 hours).

--max-replies n

Do not return more that n items in one query. The default is 10.

--ignore-cert-extension oid

Add oid to the list of ignored certificate extensions. The oid is expected to be in dotted decimal form, like 2.5.29.3. This option may be used more than once. Critical flagged certificate extensions matching one of the OIDs in the list are treated as if they are actually handled and thus the certificate won't be rejected due to an unknown critical extension. Use this option with care because extensions are usually flagged as critical for a reason.

--ignore-crl-extension oid

Add oid to the list of ignored CRL extensions. The oid is expected to be in dotted decimal form. Critical flagged CRL extensions matching one of the OIDs in the list are treated as if they are actually handled and thus the certificate won't be rejected due to an unknown critical extension. Use this option with care because extensions are usually flagged as critical for a reason.

--ignore-cert fpr|file

Entirely ignore certificates with the fingerprint fpr. As an alternative to the fingerprint a filename can be given in which case all certificates described in that file are ignored. Any argument which contains a slash, dot or tilde is considered a filename. Usual filename expansion takes place: A tilde at the start followed by a slash is replaced by the content of ‘HOME’, no slash at start describes a relative filename which will be searched at the home directory. To make sure that the file is searched in the home directory, either prepend the name with "./" or use a name which contains a dot. The format of such a file is a list of SHA-1 fingerprint, one per line with optional colons between the bytes. Empty lines and lines prefixed with a hash mark are ignored. This option is useful as a quick workaround to exclude certain certificates from the system store.

--hkp-cacert file

Use the root certificates in file for verification of the TLS certificates used with hkps (keyserver access over TLS). If the file is in PEM format a suffix of .pem is expected for file. This option may be given multiple times to add more root certificates. Tilde expansion is supported. If no hkp-cacert directive is present, dirmngr will use the system CAs.

## EXAMPLES
Here is an example on how to show dirmngr's internal table of OpenPGP keyserver addresses. The output is intended for debugging purposes and not part of a defined API.

```
  gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
```

To inhibit the use of a particular host you have noticed in one of the keyserver pools, you may use

```
 gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
```

The description of the keyserver command can be printed using

```
 gpg-connect-agent --dirmngr 'help keyserver' /bye
```

## FILES
Dirmngr makes use of several directories when running in daemon mode: There are a few configuration files to control the operation of dirmngr. By default they may all be found in the current home directory (see: [option --homedir]).

dirmngr.conf

This is the standard configuration file read by dirmngr on startup. It may contain any valid long option; the leading two dashes may not be entered and the option may not be abbreviated. This file is also read after a SIGHUP however not all options will actually have an effect. This default name may be changed on the command line (see: [option --options]). You should backup this file.

/etc/gnupg/trusted-certs

This directory should be filled with certificates of Root CAs you are trusting in checking the CRLs and signing OCSP Responses. Usually these are the same certificates you use with the applications making use of dirmngr. It is expected that each of these certificate files contain exactly one DER encoded certificate in a file with the suffix ‘.crt’ or ‘.der’. dirmngr reads those certificates on startup and when given a SIGHUP. Certificates which are not readable or do not make up a proper X.509 certificate are ignored; see the log file for details.

Applications using dirmngr (e.g. gpgsm) can request these certificates to complete a trust chain in the same way as with the extra-certs directory (see below).

Note that for OCSP responses the certificate specified using the option --ocsp-signer is always considered valid to sign OCSP requests.

/etc/gnupg/extra-certs

This directory may contain extra certificates which are preloaded into the internal cache on startup. Applications using dirmngr (e.g. gpgsm) can request cached certificates to complete a trust chain. This is convenient in cases you have a couple intermediate CA certificates or certificates usually used to sign OCSP responses. These certificates are first tried before going out to the net to look for them. These certificates must also be DER encoded and suffixed with ‘.crt’ or ‘.der’.

~/.gnupg/crls.d

This directory is used to store cached CRLs. The ‘crls.d’ part will be created by dirmngr if it does not exists but you need to make sure that the upper directory exists.

Several options control the use of trusted certificates for TLS and CRLs. Here is an Overview on the use and origin of those Root CA certificates:

System

These System root certificates are used by: FIXME

The origin of the system provided certificates depends on the platform. On Windows all certificates from the Windows System Stores ROOT and CA are used.

On other platforms the certificates are read from the first file found form this list: ‘/etc/ssl/ca-bundle.pem’, ‘/etc/ssl/certs/ca-certificates.crt’, ‘/etc/pki/tls/cert.pem’, ‘/usr/local/share/certs/ca-root-nss.crt’, ‘/etc/ssl/cert.pem’.

GnuPG

The GnuPG specific certificates stored in the directory ‘/etc/gnupg/trusted-certs’ are only used to validate CRLs.

OpenPGP keyserver

For accessing the OpenPGP keyservers the only certificates used are those set with the configuration option hkp-cacert.

OpenPGP keyserver pool

This is usually only one certificate read from the file ‘/usr/share/gnupg/gnupg/sks-keyservers.netCA.pem’. If this certificate exists it is used to access the special keyservers hkps.pool.sks-keyservers.net (or ‘hkps://keys.gnupg.net’).

Please note that gpgsm accepts Root CA certificates for its own purposes only if they are listed in its file ‘trustlist.txt’. dirmngr does not make use of this list - except FIXME.

## NOTES
To be able to see diagnostics it is often useful to put at least the following lines into the configuration file ‘~/gnupg/dirmngr.conf’:

```
log-file ~/dirmngr.log
verbose
```

You may want to check the log file to see whether all desired root CA certificates are correctly loaded.

To be able to perform OCSP requests you probably want to add the line:

```
allow-ocsp
```

To make sure that new options are read or that after the installation of a new GnuPG versions the right dirmngr version is running, you should kill an existing dirmngr so that a new instance is started as needed by the other components:

```
gpgconf --kill dirmngr
```

Direct interfaction with the dirmngr is possible by using the command

```
gpg-connect-agent --dirmngr
```

Enter HELP at the prompt to see a list of commands and enter HELP followed by a command name to get help on that command.

## SIGNALS
A running dirmngr may be controlled by signals, i.e. using the kill command to send a signal to the process.

Here is a list of supported signals:

SIGHUP

This signal flushes all internally cached CRLs as well as any cached certificates. Then the certificate cache is reinitialized as on startup. Options are re-read from the configuration file. Instead of sending this signal it is better to use

```
gpgconf --reload dirmngr
```

SIGTERM

Shuts down the process but waits until all current requests are fulfilled. If the process has received 3 of these signals and requests are still pending, a shutdown is forced. You may also use

```
gpgconf --kill dirmngr
```

instead of this signal

SIGINT

Shuts down the process immediately.

SIGUSR1

This prints some caching statistics to the log file.

## SEE ALSO
gpgsm(1), dirmngr-client(1)

The full documentation for this tool is maintained as a Texinfo manual. If GnuPG and the info program are properly installed at your site, the command

```
info gnupg
```

should give you access to the complete manual including a menu structure and an index.


gdomap

package: gnustep-base

title: gdomap(8)

summary: GNUstep Distributed Objects name server

text:
# gdomap(8)

## NAME
gdomap - GNUstep Distributed Objects name server

## SYNOPSIS
gdomap [-C|-H] [-I pidfile] [-L name] [-M name] [-N] [-P number] [-R name] [-S] [-T type] [-U name] [-a file] [-c file] [-d] [-f] [-i seconds] [-j path] [-p]

## DESCRIPTION
gdomap The gdomap daemon is used by GNUstep programs to look up distributed objects of processes running across the network (and between different user accounts on a single machine). The daemon is NOT used for lookup where two processes belonging to the same user are using a host-local connection. This manual page explains the usage of gdomap. For design and implementation information (and special notes for packagers), please see the HTML documentation installed in $GNUSTEP_SYSTEM_DOC, under Command-line Tools.

Usually the gdomap daemon is started at system boot time and binds itself to port 538. See the GNUstep Build Guide for a sample startup script.

By default gdomap probes every machine on the local network to see if there is a copy of gdomap running on it. This is done for class-C networks and subnets of class-C networks. If your host is on a class-B or class-A net then the default behaviour is to treat it as a class-C net and probe only the hosts that would be expected on a class-C network of the same number.

If you are running on a class-A or class-B network, or if your net has a large number of hosts which will not have gdomap on them - you may want to supply a configuration file listing the hosts to be probed explicitly, rather than getting gdomap to probe all hosts on the local net.

You may also want to supply the configuration file so that hosts which are not actually on your local network can still be found when your code tries to connect to a host using @"*" as the host name. NB. this functionality does not exist in OpenStep.

A configuration file consists of a list of IP addresses to be probed. The IP addresses should be in standard 'dot' notation, one per line. Empty lines are permitted in the configuration file. Anything on a line after a hash ('#') is ignored. You tell gdomap about the config file with the '-c' command line option.

gdomap uses the SIOCGIFCONF ioctl to build a list of IP addresses and netmasks for the network interface cards on your machine. On some operating systems, this facility is not available (or is broken), so you must tell gdomap the addresses and masks of the interfaces using the '-a' command line option. The file named with '-a' should contain a series of lines with space separated pairs of addresses and masks in 'dot' notation. You must NOT include loopback interfaces in this list. If you want to support broadcasting of probe information on a network, you may supply the broadcast address as a third item on the line. If your operating system has some other method of giving you a list of network interfaces and masks, please send me example code so that I can implement it in gdomap.

## OPTIONS
-C

help about configuration

-H

general help

-I

pid file to write pid

-L name

perform lookup for name then quit.

-M name

machine name for -L and -N

-N

list all names registered on host

-P number

port number required for -R option.

-R name

register name locally then quit. -S

-S

list the addresses of all gdomap servers known to host

-T type

port type for -L , -R and -U options - tcp_gdo, udp_gdo, tcp_foreign, udp_foreign.

-U name

unregister name locally then quit.

-a file

use config file for interface list.

-c file

use config file for probe.

-d

extra debug logging (normally via syslog).

-f

avoid fork() to make debugging easy

-i seconds

re-probe at this interval (roughly), min 60

-j path

place the process in a chroot jail at this path rather than in /tmp

-p

disable probing for other servers

## FILES
Use the -c option to specify a configuration file for gdomap. See under DESCRIPTION for possible configurations.

## DIAGNOSTICS
Kill with SIGUSR1 to obtain a dump of all known peers in /tmp/gdomap.dump

gdomap -N lists all registered names on the local host.

## SEE ALSO
gdomap -C gives above instructions on how to set up gdomap.

gdnc(1), GNUstep(7), gpbs(1)

The GNUstep Build Guide example rc script: <http://gnustep.made-it.com/BuildGuide/index.html#GNUSTEP.SERVICES>

## HISTORY
Work on gdomap started in October 1996.

This manual page first appeared in gnustep-base 1.7.1 (June 2003).

## AUTHORS
gdomap was written by Richard Frith-Macdonald <rfm@gnu.org>

This manual page was put together by Martin Brecher <martin@mb-itconsulting.com>.

branch: sisyphus


nss-cache-oslogin

package: google-guest-oslogin

title: nss-cache-oslogin(8)

text:
# nss-cache-oslogin(8)

## NAME
nss-cache-oslogin, libnss_cache_oslogin.so.2 - UNIX implementation for OS Login Users and Groups with local caching.

## SYNOPSIS
libnss_cache_oslogin.so.2

## DESCRIPTION
nss-cache-oslogin is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (glibc). This module provides UNIX name resolution from a local cache of users and groups configured in the Google Cloud OS Login system. The "passwd" and "group" services are supported by this module.

To use the NSS module, add "cache_oslogin" to the appropriate service lines in nsswitch.conf. It is recommended to place "cache_oslogin" after any system provided modules and before the "oslogin" module, as it is a pass-through cache.

## FILES
/etc/oslogin_passwd.cache

user cache file

/etc/oslogin_group.cache

group cache file

## NOTES
Documentation for the Google Cloud OS Login service is available online at https://cloud.google.com/compute/docs/oslogin

## SEE ALSO
nss-oslogin(5), nsswitch.conf(5), nss(5), getent(1), initgroups(3)


nss-oslogin

title: nss-oslogin(8)

text:
# nss-oslogin(8)

## NAME
nss-oslogin, libnss_oslogin.so.2 - UNIX implementation for OS Login Users and Groups.

## SYNOPSIS
libnss_oslogin.so.2

## DESCRIPTION
nss-oslogin is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (glibc). This module provides UNIX name resolution for users and groups configured through the Google Cloud OS Login system. The "passwd", "group", and "initgroups" services are supported by this module.

To use the NSS module, add "oslogin" to the appropriate service lines in nsswitch.conf. It is recommended to place "oslogin" as the last entry for each service.

## NOTES
Documentation for the Google Cloud OS Login service is available online at https://cloud.google.com/compute/docs/oslogin

## SEE ALSO
nss-cache-oslogin(8), nsswitch.conf(5), nss(5), getent(1), initgroups(3)


gpart

package: gpart

title: gpart(8)

summary: guess PC-type hard disk partitions

text:
# gpart(8)

## NAME
gpart - guess PC-type hard disk partitions

## SYNOPSIS
gpart [options] device

Options: [-b <backup MBR>][-C c,h,s][-c][-d][-E][-e][-f] [-g][-h][-i][-K <last-sector>][-k <# of sectors>] [-L] [-l <log file>][-n <increment>] [-q][-s <sector-size>] [-t <module-name>][-V][-v] [-W <device>][-w <module-name, weight>]

## DESCRIPTION
gpart tries to guess which partitions are on a hard disk. If the primary partition table has been lost, overwritten or destroyed the partitions still exist on the disk but the operating system cannot access them.

gpart ignores the primary partition table and scans the disk (or disk image, file) sector after sector for several filesystem/partition types. It does so by "asking" filesystem recognition modules if they think a given sequence of sectors resembles the beginning of a filesystem or partition type. Currently the following filesystem types are known to gpart (listed by module names) :

beos

BeOS filesystem type.

bsddl

FreeBSD/NetBSD/386BSD disklabel sub-partitioning scheme used on Intel platforms.

ext2

Linux second extended filesystem.

fat

MS-DOS FAT12/16/32 "filesystems".

hpfs

IBM OS/2 High Performance filesystem.

hmlvm

Linux LVM physical volumes (LVM by Heinz Mauelshagen).

lswap

Linux swap partitions (versions 0 and 1).

minix

The Minix operating system filesystem type.

ntfs

MS Windows NT/2000 filesystem.

qnx4

QNX 4.x filesystem.

reiserfs

The Reiser filesystem (version 3.5.X, X > 11, 3.6.X).

s86dl

Sun Solaris on Intel platforms uses a sub-partitioning scheme on PC hard disks similar to the BSD disklabels.

xfs

Silicon Graphic's journalling filesystem for Linux.

More filesystem guessing modules can be added at runtime (see the -t option). Please consult the gpart README file for detailed explanations on how to create guessing modules. All modules are accompanied by a guessing weight factor which denotes how "educated" their guesses are compared to other modules. This weight can be changed if a certain module keeps on mis-identifying a partition.

Naturally only partitions which have been formatted in some way can be recognized. If the type of a partition entry in the primary partition table is changed from x to y while the filesystem is still of type x, gpart will also still guess a type x.

No checks are performed whether a found filesystem is clean or even consistent/mountable, so it is quite possible that gpart may identify partitions which existed prior to the current partitioning scheme of the disk. Especially on large disks old file system headers/superblocks may be present a long time until they are finally overwritten with user data.

It should be stressed that gpart does a very heuristic job, never believe its output without any plausability checks. It can be easily right in its guesswork but it can also be terribly wrong. You have been warned.

After having found a list of possible partition types, the list is checked for consistency. For example, a partition which overlaps with the previous one will be discarded. All remaining partitions are labelled with one of the following attributes: "primary", "logical", "orphaned" or "invalid".

A partition labelled "orphaned" is a logical partition which seems ok but is missed in the chain of logical partitions. This may occur if a logical partition is deleted from the extended partition table without overwriting the actual disk space.

An "invalid" partition is one that cannot be accepted because of various reasons. If a consistent primary partition table was created in this process it is printed and can be written to a file or device.

## EXTENDED PARTITIONS
If the disk/file to be examined consists of primary partitions only, gpart has quite a good chance to identify them. Extended partitions on the other hand can result in a lot of problems.

Extended partitions are realized as a linked list of extended partition tables, each of which include an entry pointing to a logical partition. The size of an extended partition depends on where the last logical partition ends. This means that extended partitions may include "holes", unallocated disk space which should only be assigned to logical, not primary partitions.

gpart tries to do its best to check a found chain of logical partitions but there are very many possible points of failure. If "good" fdisk programs are used to create extended partitions, the resulting tables consist of a zeroed boot record and the four partition entries of which at least two should be marked unused. Unfortunately e.g. the fdisk program shipped with Windows NT does not seem to zero out the boot record area so gpart has to be overly tolerant in recognizing extended partition tables. This tolerance may result in quite stupid guesses.

## DISK TRANSFERS
If you want to investigate hard disks from other systems you should note down the geometry (number of cylinders, heads per cylinder and sectors per head) used for that disk, and tell gpart about this geometry.

Investigating disks from machines with a different endianness than the scanning one has not been tested at all, and is currently not recommended.

## LARGE DISKS
gpart relies on the OS reporting the correct disk geometry. Unfortunately sometimes the OS may report a geometry smaller the the actual one (e.g. disks with more than 1024 or 16384 cylinder).

gpart checks if guessed partitions extend beyond the disk size and marks those "invalid", but may be mistaken in case the disk size is calculated from an incorrect geometry. For instance if a disk with the geometry 1028/255/63 should be scanned, and the OS reports 1024/255/63 gpart should be called like

gpart -C 1028,255,63 <other options> <device>

## PRECAUTIONS
gpart may be of some help when the primary partition table was lost or destroyed but it can under no circumstances replace proper disk/partition table backups. To save the master boot record (MBR) including the primary partition table to a file type

dd if=/dev/hda of=mbr bs=512 count=1

exchanging /dev/hda with the block device name of the disk in question. This should be done for all disks in the system. To restore the primary partition table without overwriting the MBR type

dd if=mbr of=/dev/hda bs=1 count=64 skip=446 seek=446

Warning: make sure that all parameters are typed as shown and that the disk device is correct. Failing to do so may result in severe filesystem corruption. The saved file should be stored in a safe place like a floppy disk.

## OPTIONS
-b backupfile

If the guessed primary partition table seems consistent and should be written (see the -W option) backup the current MBR into the specified file.

-C c,h,s

Set the disk geometry (cylinders, heads, sectors) for the scan. This is useful if a disk should be scanned which was partitioned using a different geometry, if the device is a disk-image or if the disk geometry cannot be retrieved through the PCs BIOS. No spaces are allowed between the numbers, unless all three are enclosed in quotes.

-c

Check/compare mode (implies the -q quiet option). After the scan is done, the resulting primary partition table is compared to the existing one. The return code of gpart then contains the number of differences (0 if they are identical except for the boot/active flag which cannot be guessed). This option has no effect if -d is given on the command line.

-d

Do not start the guessing loop. Useful if the partition table should be printed (in combination with the -v option) without actually scanning for partitions.

-E

Do not try to identify extended partition tables. If there are extended partitions on the given device gpart will most certainly complain about too many primary partitions because there can be only four primary partitions. Existing logical partitions will be listed as primary ones.

-e

Do not skip disk read errors. If this option is given, and short disk reads or general disk read errors (EIO) are encountered, gpart will exit. If not given, the program tries to continue.

-f

Full scan. When a possible partition is found, gpart normally skips all sectors this entry seems to occupy and continues the scan from the end of the last possible partition. The disk scan can take quite a while if this option is given, be patient.

-g

Do not try to get the disk geometry from the OS. If the device is no block or character device but a plain file this option should be supplied. If the file to be scanned is an image of a disk, the geometry can be given by the -C option.

-h

Show some help.

-i

Run interactively. Each time a possible partition is identified the user is asked for confirmation.

-K last sector

Scan only up to the given sector or the end of the file or device whichever comes first.

-k sectors

Skip given number of sectors before the scan. Potentially useful if a partition is looked for at the end of a large disk.

-L

List available filesystem/partition type modules and their weights, then exit.

-l logfile

Log output to the given file (even if -q was supplied).

-n increment

Scan increment: number of sectors or "s" for single sector increment, "h" for an increment of sectors per head (depends on geometry) or "c" for cylinder increment. The increment also influences the condition where extended partition tables are searched: if the scan increment is "s" (i.e. 1) extended partition tables are required to be on a head boundary, otherwise they must be on a cylinder boundary.

If the disk geometry could not be retrieved and no geometry was given on the command line, the default increment is one sector.

-q

Quiet/no output mode. However if a logfile was specified (see -l option) all output is written to that file. This option overrides the -i interactive mode.

-s sector size

Preset medium sector size. gpart tries to find out the sector size but may fail in doing so. Probed sector sizes are 2^i, i=9..14 (512 to 16384 bytes). The default medium sector size is 512 bytes.

-V

Show version number.

-v

Be verbose. This option can be given more than once resulting in quite a lot of information.

-W device

Write partition table. If a consistent primary partition table has been guessed it can be written to the specified file or device. The supplied device can be the same as the scanned one. Additionally the guessed partition entries can be edited. No checks are performed on the entered values, thus the resulting table is allowed to be highly inconsistent. Please beware.

Warning: The guessed partition table should be checked very carefully before writing it back. You can always write the guessed partition table into a plain file and write this into sector 0 using dd(1) (see section PRECAUTIONS above).

-w module name,weight

Put the given module at the head of the module chain and assign a new weight to that module. All modules are given an initial weight of 1.0. A weight of 0 deactivates the filesystem recognition module. Again no spaces are allowed.

Default settings are "-n h".

## EXAMPLES
- To scan the first IDE hard disk under Linux using default settings type

gpart /dev/hda

- To print the primary partition table of the third IDE drive without starting the scan loop in FreeBSD type

gpart -vvd /dev/wd2

- If lilo(8) was installed in the master boot record (MBR) of a hard disk it saves the contents of the first sector in a file called /boot/boot.<major/minor>. To list the partitions contained in such a file type e.g.

gpart -vdg /boot/boot.0300

If the partition table contains an extended partition, gpart will complain about invalid extended partition tables because the extended entry points to sectors not within that file.

- Usually the first primary partition starts on the second head. If gpart cannot identify the first partition properly this may not be the case. gpart can be told to start the scan directly from sector one of the disk, using the sector-wise scan mode:

gpart -k 1 -n s /dev/hdb

- Suppose gpart identifies an NTFS partition as FAT on a certain disk. In this situation the "ntfs" module should be made the first module to be probed and given a weight higher than the usual weight of 1.0:

gpart -w ntfs,1.5 /dev/hdb

To list the available modules and their weights use the -L option.

- Suppose the hard disk contains a lot of virtual machines and the filesystems inside the VMs isn't used outside. Thereby deactivating the guessing of those filesystems reduces the noise and false positives during the scan process.

Set the module weight to 0 to deactivate guessing it.

For example: The hard disk is formatted with XFS and EXT3 filesystems only and there are a lot of Windows VMs on these filesystems. Thereby deactivating of FAT and NTFS guesses reduce the noise during the scan process and produces a more accurate guess.

gpart -w fat,0 -w ntfs,0 /dev/hdb

- After having checked the output of gpart at least thrice, the primary partition table can be written back to the device this way:

gpart -W /dev/sdc /dev/sdc

This of course may be extremely dangerous to your health and social security, so beware.

- A hard disk with 63 sectors per head is scanned in steps of 63 sectors. To perform the scan on every second head while skipping the first 1008 sectors type

gpart -k 1008 -n 126 /dev/sda

- If you want to see how easily gpart can be mislead, and how many probable partition starts are on a disk, search the whole disk really sector by sector, writing all output to a logfile:

gpart -vvfn s -ql /tmp/gpart.log /dev/sd2 &

Usually gpart will not be able to produce an educated guess of the primary partition table in this mode. The logfile however may contain enough hints to manually reconstruct the partition table.

## FILES
/dev/*

Hard disk block devices. The naming scheme of hard disk block devices is OS dependent, consult your system manuals for more information.

## DIAGNOSTICS
There are many error message types, all of them should be self-explanatory. Complain if they are not.

## BUGS
gpart is beta software, so expect buggy behaviour.

- gpart only accepts extended partition links with one logical partition. There may be fdisk variants out there creating links with up to three logical partition entries but these are not accepted.

## TO DO
- Support big-endian architectures.

- Test on 64-bit architectures.

- Look for boot manager partitions (e.g. OS/2 BM).

- Think about reconstructing logical partition chains.

## AUTHOR
Please send bug reports, suggestions, comments etc. to

Michail Brzitwa <michail@brzitwa.de>

## SEE ALSO
fdisk(8).


gparted

package: gparted

title: gparted(8)

text:
# gparted(8)

## NAME
gparted - GNOME Partition Editor for manipulating disk partitions.

## SYNOPSIS
gparted [device]...

## DESCRIPTION
The gparted application is the GNOME partition editor for creating, reorganizing, and deleting disk partitions.

A disk device can be subdivided into one or more partitions. The gparted application enables you to change the partition organization on a disk device while preserving the contents of the partition.

With gparted you can accomplish the following tasks:

- Create a partition table on a disk device.

- Enable and disable partition flags such as boot and hidden.

- Perform actions with partitions such as create, delete, resize, move, check, label, copy, and paste.

More documentation can be found in the application help manual, and online at:

https://gparted.org

## EXAMPLES
You can run gparted from a command line and specify one or more disk devices.

For example, to start gparted with the devices /dev/sda and /dev/sdc you would use the following command:

gparted /dev/sda /dev/sdc

## NOTES
Editing partitions has the potential to cause LOSS of DATA.

The gparted application is designed to enable you to edit partitions while reducing the risk of data loss. The application is carefully tested and is used by the GParted project team. However, loss of data might occur due to software bugs, hardware problems, or power failure.

You can help to reduce the risk of data loss by not mounting or unmounting partitions outside of the gparted application while gparted is running.

You are advised to BACKUP your DATA before using the gparted application.

## REPORTING BUGS
Report bugs at:

https://gparted.org/bugs.php

## AUTHOR
Manual page written by Curtis Gedak <gedakc@users.sf.net>

## SEE ALSO
parted(8), fdisk(8), mkfs(8), ntfsprogs(8)


gpm

package: gpm

title: gpm(8)

text:
# gpm(8)

## NAME
gpm - a cut and paste utility and mouse server for virtual consoles

## SYNOPSIS
gpm [ options ]

## DESCRIPTION
This package tries to be a useful mouse server for applications running on the Linux console. It is based on the "selection" package, and some of its code comes from selection itself. This package is intended as a replacement for "selection" as a cut-and-paste mechanism; it also provides additional facilities. The "selection" package offered the first cut-and-paste implementation for Linux using two mouse buttons, and the cut buffer is still called "selection buffer" or just "selection" throughout this document. The information below is extracted from the texinfo file, which is the preferred source of information.

The gpm executable is meant to act like a daemon (thus, gpmd would be a better name for it). This section is meant to describe the command-line options for gpm, while its internals are outlined in the next section.

Due to restrictions in the ioctl(TIOCLINUX) system call, gpm must be run by the superuser. The restrictions have been added in the last 1.1 kernels to fix a security hole related to selection and screen dumping.

The server can be configured to match the user's taste, and any application using the mouse will inherit the server's attitude. From release 1.02 up to 1.19.2 is was possible for any user logged on the system console to change the mouse feeling using the -q option. This is no longer possible for security reasons.

As of 0.97 the server program puts itself in the background. To kill gpm you can just reinvoke it with the -k cmdline switch, although killall gpm can be a better choice.

## SPECIAL COMMANDS
Version 1.10 adds the capability to execute special commands on certain circumstances. Special commands default to rebooting and halting the system, but the user can specify his/her personal choice. The capability to invoke commands using the mouse is a handy one for programmers, because it allows to issue a clean shutdown when the keyboard is locked and no network is available to restore the system to a sane state.

Special commands are toggled by triple-clicking the left and right button -- an unlikely event during normal mouse usage. The easiest way to triple-click is pressing one of the buttons and triple-click the other one. When special processing is toggled, a message appears on the console (and the speaker beeps twice, if you have a speaker); if the user releases all the buttons and presses one of them again within three seconds, then the special command corresponding to the button is executed.

The default special commands are:

left button

Reboot the system by signalling the init process

middle button (if any)

Execute /sbin/shutdown -h now

right button

Execute /sbin/shutdown -r now

The -S command line switch enables special command processing and allows to change the three special commands. To accept the default commands use -S "" (i.e., specify an empty argument). To specify your own commands, use a colon-separated list to specify commands associated to the left, middle and right button. If any of the commands is empty, it is interpreted as `send a signal to the init process'. This particular operation is supported, in addition to executing external commands, because sometimes bad bugs put the system to the impossibility to fork; in these rare case the programmer should be able to shutdown the system anyways, and killing init from a running process is the only way to do it.

As an example, -S ":telinit 1:/sbin/halt", associates killing init to the left button, going single user to the middle one, and halting the system to the right button.

System administrators should obviously be careful about special commands, as gpm runs with superuser permissions. Special commands are best suited for computers whose mouse can be physically accessed only by trusted people.

## COMMAND LINE OPTIONS
Available command line options are the following:

-a accel

Set the acceleration value used when a single motion event is longer than delta (see -d).

-A[limit]

Start up with selection pasting disabled. This is intended as a security measure; a plausible attack on a system seems to be to stuff a nasty shell command into the selection buffer (rm -rf /) including the terminating line break, then all the victim has to do is click the middle mouse button .. As of version 1.17.2, this has developed into a more general aging mechanism; the gpm daemon can disable (age) selection pasting automatically after a period of inactivity. To enable this mode just give the optional limit parameter (no space in between !) which is interpreted as the time in seconds for which a selection is considered valid and pastable. As of version 1.15.7, a trivial program called disable-paste is provided. The following makes a good addition to /etc/profile if you allow multiple users to work on your console.

case $( /usr/bin/tty ) in

/dev/tty[0-9]*) /usr/bin/disable-paste ;;

esac

-b baud

Set the baud rate.

-B sequence

Set the button sequence. 123 is the normal sequence, 321 can be used by left-handed people, and 132 can be useful with two-button mice (especially within Emacs). All the button permutations are allowable.

-d delta

Set the delta value. When a single motion event is longer than delta, accel is used as a multiplying factor. (Must be 2 or above)

-D

Do not automatically enter background operation when started, and log messages to the standard error stream, not the syslog mechanism. This is useful for debugging; in previous releases it was done with a compile-time option.

-g number

With glidepoint devices, emulate the specified button with tapping. number must be 1, 2, or 3, and refers to the button number before the -B button remapping is performed. This option applies to the mman and ps2 decoding. No button is emulated by default because the ps2 tapping is incompatible with some normal ps2 mice

-h

Print a summary of command line options.

-i interval

Set interval to be used as an upper time limit for multiple clicks. If the interval between button-up and button-down events is less than limit, the press is considered a double or triple click. Time is in milliseconds.

-k

Kill a running gpm. This can be used by busmouse users to kill gpm before running X (unless they use -R or the single-open limitation is removed from the kernel).

-l charset

Choose the inword() look up table. The charset argument is a list of characters. - is used to specify a range and \ is used to escape the next character or to provide octal codes. Only visible character can appear in charset because control characters can't appear in text-mode video memory, whence selection is cut.

-m filename

Choose the mouse file to open. Must be before -t and -o.

-M

Enable multiple mode. The daemon will read two different mouse devices. Any subsequent option will refer to the second device, while any preceding option will be used for the first device. This option automatically forces the repeater (-R) option on.

-o list-of-extra-options

The option works similary to the ``-o'' option of mount; it is used to specify a list of ``extra options'' that are specific to each mouse type. The list is comma-separated. The options dtr, rts or both are used by the serial initialization to toggle the modem lines like, compatibly with earlier gpm versions; note however that using -o dtr associated with non-plain-serial mouse types may now generate an error. And by the way, use -o after -m and after -t.

-p

Forces the pointer to be visible while selecting. This is the behaviour of selection-1.7, but it is sometimes confusing. The default is not to show the pointer, which can be confusing as well.

-r number

Set the responsiveness. A higher responsiveness is used for a faster cursor motion.

-R[name]

Causes gpm to act as a repeater: any mouse data received while in graphic mode will be produced on the fifo /dev/gpmdata in protocol name, given as an optional argument (no space in between !). In principle, you can use the same names as for the -t option, although repeating into some protocols may not be implemented for a while. In addition, you can specify raw as the name, to repeat the mouse data byte by byte, without any protocol translation. If name is omitted, it defaults to msc. Using gpm in repeater mode, you can configure the X server to use its fifo as a mouse device. This option is useful for bus-mouse owners to override the single-open limitation. It is also an easy way to manage those stupid dual-mode mice which force you to keep the middle button down while changing video mode. The option is forced on by the -M option.

-s number

Set the sample rate for the mouse device.

-S commands

Enable special-command processing, and optionally specify custom commands as a colon-separated list. See above for a detailed description of special commands.

-t name

Set the mouse type. Use -t help to get a list of allowable types. Since version 1.18.1, the list also shows which protocols are available as repeaters (see -R above), by marking them with an asterisk (``*''). Use -t after you selected the mouse device with -m.

-v

Print version information and exit.

-V[verbosity increment]

Raise or decrease the maximum level of messages that will be logged. Thus a positive argument has the effect of making the program more verbose. One can also give a negative argument to hush the program; due to getopt(3) rules, any optional argument needs to be passed without a space in between! When omitting the argument, the increment defaults to 1. Default verbosity level is 5 (LOG_NOTICE).

-2

Force two buttons. This means that the middle button, if any, will be taken as it was the right one.

-3

Force three buttons. By default the mouse is considered to be a 2-buttons one, until the middle button is pressed. If three buttons are there, the right one is used to extend the selection, and the middle one is used to paste it. Beware: if you use the -3 option with a 2-buttons mouse, you won't be able to paste the selection.

## OPERATION
To select text press the left mouse button and drag the mouse. To paste text in the same or another console, press the middle button. The right button is used to extend the selection, like in `xterm'.

Two-button mice use the right button to paste text.

Double and triple clicks select whole word and whole lines. Use of the `-p' option is recommended for best visual feedback.

If a trailing space after the contents of a line is highlighted, and if there is no other text on the remainder of the line, the rest of the line will be selected automatically. If a number of lines are selected, highlighted trailing spaces on each line will be removed from the selection buffer.

Any output on the virtual console holding the selection will clear the highlighted selection from the screen, to maintain integrity of the display, although the contents of the paste buffer will be unaffected.

The selection mechanism is disabled if the controlling virtual console is placed in graphics mode, for example when running X11, and is re-enabled when text mode is resumed. (But see BUGS section below.)

## BUGS
The gpm server may have problems interacting with X: if your mouse is a single-open device (i.e. a bus mouse), you should kill gpm before starting X, or use the -R option (see above). To kill gpm just invoke gpm -k. This problem doesn't apply to serial mice.

Two instances of gpm can't run on the same system. If you have two mice use the -M option (see above).

While the current console is in graphic mode, gpm sleeps until text mode is back (unless -R is used). Thus, it won't reply to clients. Anyways, it is unlikely that mouse-eager clients will spur out in hidden consoles.

The clients shipped out with gpm are not updated, thus there are potential security risks when using them.

## AUTHORS

```
Andrew Haylett <ajh@gec-mrc.co.uk> (the original selection code)
Ian Zimmerman <itz@speakeasy.org> (old maintainer)
Alessandro Rubini <rubini@linux.it> (old maintainer (still helps a lot))
Nico Schottelius <nico@schottelius.org> (maintainer)
Many many contributors, to both selection and gpm.
```

## MAINTAINERS
The current maintainer is Nico Schottelius. But without the help of Alessandro Rubini and the mailing list it would be impossible for him to maintain gpm. The development mailing list can be reached under gpm@lists.linux.it. More information on the list is in the README file part of the source distribution of gpm.

## FILES

```
/var/run/gpm.pid The PID of the running gpm
/dev/gpmctl     A control socket for clients
/dev/gpmdata    The fifo written to by a repeater (`-R') daemon.
```

## SEE ALSO

```
 mev(1)        A sample client for the gpm daemon.
 gpm-root(1)   An handler for Control-Mouse events.
```

The info file about `gpm', which gives more complete information and explains how to write a gpm client.


gpsd

package: gpsd

title: gpsd(8)

summary: interface daemon for GPS receivers

text:
# gpsd(8)

## NAME
gpsd - interface daemon for GPS receivers

## SYNOPSIS
gpsd [OPTIONS]

gpsd -h

gpsd -V

## QUICK START
If you have a GPS attached on the lowest-numbered USB port of a Linux system, and want to read reports from it on TCP/IP port 2947, it will normally suffice to do this, as root:

```
# gpsd /dev/ttyUSB0
```

For the lowest-numbered serial port:

```
# gpsd /dev/ttyS0
```

gpsd may be started as a normal user, or by using sudo, but some functionality will be lost. Best to start as root. See SECURITY AND PERMISSIONS ISSUES below.

Change the device number as appropriate if you need to use a different port. Command-line flags enable verbose logging, a control port, and other optional extras but should not be needed for basic operation; the one exception, on very badly designed hardware, might be -b (which see).

On Linux systems supporting udev, gpsd is normally started automatically when a USB plugin event fires (if it is not already running) and is handed the name of the newly active device. In that case no invocation is required at all.

For your initial tests set your GPS hardware to speak NMEA, as gpsd is guaranteed to be able to process that. If your GPS has a native or binary mode with better performance that gpsd knows how to speak, gpsd may autoconfigure that mode.

You can verify correct operation by first starting gpsd. Then xgps, the X windows test client or cgps the curses based terminal client.

If you have problems, the GPSD project maintains helpful information online. Some links are at the end of this man page.

## DESCRIPTION
gpsd is a monitor daemon that collects information from GPSes, differential-GPS radios, or AIS receivers attached to the host machine. Each GPS, DGPS radio, or AIS receiver is expected to be directly connected to the host via a USB or RS232C serial device. The serial device may be specified to gpsd at startup, or it may be set via a command shipped down a local control socket (e.g. by a USB hotplug script). Given a GPS device by either means, gpsd discovers the correct port speed and protocol for it.

gpsd should be able to query any GPS that speaks either the standard textual NMEA 0183 protocol, or the (differing) extended NMEA dialects used by MTK-3301, iTrax, Motorola OnCore, Sony CXD2951, Ashtech/Thales and some other devices. It can also interpret the binary protocols used by EverMore, Garmin, Javad, Navcom, Rockwell/Zodiac, SiRF, Trimble, and u-blox devices. Under Linux it can read NMEA2000 packets through the kernel CAN socket. It can read heading and attitude information from the TNT Revolution digital compasses.

The GPS reporting formats supported by your binary of gpsd may differ depending on how it was compiled; general-purpose versions support many, but it can be built with protocol subsets down to a singleton for use in constrained environments. For a list of the GPS protocols supported by your binary, see the output of gpsd -l

gpsd effectively hides the differences among the GPS types it supports. It also knows about and uses commands that tune these GPSes for lower latency. By using gpsd as an intermediary, applications avoid contention for serial devices.

gpsd can use differential-GPS corrections from a DGPS radio or over the net, from a ground station running a DGPSIP server or a Ntrip broadcaster that reports RTCM-104 data; this may shrink position errors. When gpsd opens a serial device emitting RTCM-104, it automatically recognizes this and uses the device as a correction source for all connected GPSes that accept RTCM corrections (this is dependent on the type of the GPS; not all GPSes have the firmware capability to accept RTCM correction packets).

Client applications typically communicate with gpsd via a TCP/IP port, port 2947 by default. Both IPv4 and IPv6 connections are supported and a client may connect via either.

## OPTIONS
The program accepts the following options:

-?, -h, ---help

Display help message and terminate.

-b, --readonly

Broken-device-safety mode, otherwise known as read-only mode. A few bluetooth and USB receivers lock up or become totally inaccessible when probed or reconfigured; see the hardware compatibility list on the GPSD project website for details. This switch prevents gpsd from writing to a receiver. This means that gpsd cannot configure the receiver for optimal performance, but it also means that gpsd cannot break the receiver. A better solution would be for Bluetooth to not be so fragile. A platform independent method to identify serial-over-Bluetooth devices would also be nice.

-D LVL, --debug LVL

Set debug level. Default is 0. At debug levels 2 and above, gpsd reports incoming sentence and actions to standard error if gpsd is in the foreground (-N) or to syslog if in the background. See LOGGING below.

-F FILE, --sockfile FILE

Create a control socket for device addition and removal commands. Default is None. You must specify a valid pathname on your local filesystem; this will be created as a Unix-domain socket to which you can write commands that edit the daemon’s internal device list.

-f FRAME, --framing FRAME

Fix the framing to the GNSS device. The framing parameter is of the form: [78][ENO][012]. Most GNSS are 8N1. Some Trimble default to 8O1. The default is to search for the correct framing.

-G, --listenany

This flag causes gpsd to listen on all addresses (INADDR_ANY) rather than just the loop back (INADDR_LOOPBACK) address. For the sake of privacy and security, gpsd information is private by default to the local machine until the user makes an effort to expose this to the world.

-l, --drivers

List all drivers compiled into this gpsd instance. The letters to the left of each driver name are the gpsd control commands supported by that driver. Then exit.

-n, --nowait

Don’t wait for a client to connect before polling whatever GPS is associated with it. Some RS232 GPSes wait in a standby mode (drawing less power) when the host machine is not asserting DTR, and some cellphone and handheld embedded GPSes have similar behaviors. Accordingly, waiting for a watch request to open the device may save battery power. (This capability is rare in consumer-grade devices). You should use this option if you plan to use gpsd to provide reference clock information to ntpd or chronyd. This option will also enable clients to see data from the receiver sooner on connection.

-N, --foreground

Don’t daemonize; run in foreground. This switch is mainly useful for debugging.

-p, --passive

Passive mode. Do not autoconfigure the receiver, but allow manual configuration changes.

-P FILE, --pidfile FILE

Specify the name and path to record the daemon’s process ID.

-r, --badtime

Use GPS time even with no current fix. Some GPSs have battery powered Real Time Clocks (RTC’s) built in, making them a valid time source even before a fix is acquired. This can be useful on a Raspberry Pi, or other device that has no battery powered RTC, and thus has no valid time at startup. Use with caution.

--port PORT, -S PORT

Set TCP/IP port on which to listen for GPSD clients (default is 2947).

-s SPEED, --speed SPEED

Fix the serial port speed to the GNSS device. Allowed speeds are: 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800 and 921600. The default is to autobaud. Note that some devices with integrated USB ignore port speed.

-V, --version

Dump version and exit.

Arguments are interpreted as the names of data sources. Normally, a data source is the device pathname of a local device from which the daemon may expect GPS data. But there are three other special source types recognized, for a total of four:

Local serial or USB device

A normal Unix device name of a serial or USB device to which a sensor is attached. Examples: /dev/ttyS0, or /dev/ttyUSB0.

Local PPS device

A normal Unix device name of a PPS device to which a PPS source is attached. The device name must start with "/dev/pps" and a local serial or USB GPS device must also be available. Example: /dev/pps0.

TCP feed

A URI with the prefix "tcp://", followed by a hostname, a colon, and a port number. The daemon will open a socket to the indicated address and port and read data packets from it, which will be interpreted as though they had been issued by a serial device. Example: tcp://data.aishub.net:4006.

UDP feed

A URI with the prefix "udp://", followed by a hostname, a colon, and a port number. The daemon will open a socket listening for UDP datagrams arriving in the indicated address and port, which will be interpreted as though they had been issued by a serial device. Example: udp://127.0.0.1:5000.

Ntrip caster

A URI with the prefix "ntrip://" followed by the name of an Ntrip caster (Ntrip is a protocol for broadcasting differential-GPS fixes over the net). For Ntrip services that require authentication, a prefix of the form "username:password@" can be added before the name of the Ntrip broadcaster. For Ntrip service, you must specify which stream to use; the stream is given in the form "/streamname". An example DGPSIP URI could be "dgpsip://dgpsip.example.com" and a Ntrip URI could be "ntrip://foo:bar@ntrip.example.com:80/example-stream". Corrections from the caster will be sent to each attached GPS with the capability to accept them.

DGPSIP server

A URI with the prefix "dgpsip://" followed by a hostname, a colon, and an optional colon-separated port number (defaulting to 2101). The daemon will handshake with the DGPSIP server and read RTCM2 correction data from it. Corrections from the server will be set to each attached GPS with the capability to accept them. Example: dgpsip://dgps.wsrcc.com:2101.

Remote gpsd feed

A URI with the prefix "gpsd://", followed by a hostname and optionally a colon and a port number (if the port is absent the default gpsd port will be used). Then followed optionally by a second colon and the remote device name The daemon will open a socket to the indicated address and port and emulate a gpsd client, collecting JSON reports from the remote gpsd instance that will be passed to local clients. Example: gpsd://gpsd.io:2947:/dev/ttyAMA0.

NMEA2000 CAN data

A URI with the prefix "nmea2000://", followed by a CAN devicename. Only Linux socket CAN interfaces are supported. The interface must be configured to receive CAN messages before gpsd can be started. If there is more than one unit on the CAN bus that provides GPS data, gpsd chooses the unit from which a GPS message is first seen. Example: nmea2000://can0.

(The "ais:://" source type supported in some older versions of the daemon has been retired in favor of the more general "tcp://".)

Additionally, two serial device name have a side effect, if your binary was compiled with the MAGIC_HAT option:

/dev/ttyAMA0

The UART device on a Raspberry Pi. Has the side effect of opening /dev/pps0 for RFC2783 1PPS data.

/dev/gpsd0

Generic GPS device 0. Has the side effect of opening /dev/pps0 for RFC2783 1PPS data.

Note, however, that if /dev/pps0 is the fake "ktimer" PPS, then /dev/pps1 will be used instead.

Internally, the daemon maintains a device pool holding the pathnames of devices and remote servers known to the daemon. Initially, this list is the list of device-name arguments specified on the command line. That list may be empty, in which case the daemon will have no devices on its search list until they are added by a control-socket command. Daemon startup will abort with an error if no devices and no control socket is specified.

When a device is activated (i.e. a client requests data from it), gpsd attempts to execute a hook from /etc/gpsd/device-hook with first command line argument set to the pathname of the device and the second to ACTIVATE. On deactivation, it does the same passing DEACTIVATE for the second argument.

gpsd can export data to client applications in three ways: via a sockets interface, via a shared-memory segment, and via D-Bus. The next three major sections describe these interfaces.

## LOGGING
When gpsd is running as a daemon (not in the foreground) is sends all of its logging to syslog(3). Logging is sent with ident "gpsd" using facility "LOG_USER".

If you are using syslog-ng, then you can send all gpsd logs to a file /var/log/gpsd. Put this at the end of your /etc/syslog-ng/syslog-ng.conf file:

```
destination gpsdf { file("/var/log/gpsd"); };
filter f_gpsd { program("gpsd"); };
log { source(src); filter(f_gpsd); destination(gpsdf); };
```

## THE SOCKET INTERFACE
Clients may communicate with the daemon via textual request and responses over a socket. It is a bad idea for applications to speak the protocol directly: rather, they should use the libgps client library and take appropriate care to conditionalize their code on the major and minor protocol version symbols.

The request-response protocol for the socket interface is fully documented in gpsd_json(5).

## SHARED-MEMORY AND DBUS INTERFACES
gpsd has two other (read-only) interfaces.

Whenever the daemon recognizes a packet from any attached device, it writes the accumulated state from that device to a shared memory segment. The C and C++ client libraries shipped with GPSD can read this segment. Client methods, and various restrictions associated with the read-only nature of this interface, are documented at libgps(3). The shared-memory interface is intended primarily for embedded deployments in which gpsd monitors a single device, and its principal advantage is that a daemon instance configured with shared memory but without the sockets interface loses a significant amount of runtime weight.

The daemon may be configured to emit a D-Bus signal each time an attached device delivers a fix. The signal path is "path /org/gpsd", the signal interface is "org.gpsd", and the signal name is "fix". The signal payload layout is as follows:

Table 1. Satellite object

Type

Description

DBUS_TYPE_DOUBLE

Time (seconds since Unix epoch)

DBUS_TYPE_INT32

mode

DBUS_TYPE_DOUBLE

Time uncertainty (seconds).

DBUS_TYPE_DOUBLE

Latitude in degrees.

DBUS_TYPE_DOUBLE

Longitude in degrees.

DBUS_TYPE_DOUBLE

Horizontal uncertainty in meter.

DBUS_TYPE_DOUBLE

Altitude MSL in meters.

DBUS_TYPE_DOUBLE

Altitude uncertainty in meters.

DBUS_TYPE_DOUBLE

Course in degrees from true north.

DBUS_TYPE_DOUBLE

Course uncertainty in meters

DBUS_TYPE_DOUBLE

Speed, meters per second.

DBUS_TYPE_DOUBLE

Speed uncertainty in meters per second.

DBUS_TYPE_DOUBLE

Climb, meters per second.

DBUS_TYPE_DOUBLE

Climb uncertainty in meters per second.

DBUS_TYPE_STRING

Device name

Uncertainty values are provided by the GNSS receiver. Check your

receiver documentation to see if is specifies what its "uncertainty" means.

## GPS DEVICE MANAGEMENT
gpsd maintains an internal list of GPS devices (the "device pool"). If you specify devices on the command line, the list is initialized with those pathnames, otherwise the list starts empty. Commands to add and remove GPS device paths from the daemon’s device list must be written to a local Unix-domain socket which will be accessible only to programs running as root. This control socket will be located wherever the -F option specifies it.

A device may will also be dropped from the pool if GPSD gets a zero length read from it. This end-of-file condition indicates that the device has been disconnected.

When gpsd is installed along with working hotplug notifier scripts feeding it device-add commands over the control socket, gpsd should require no configuration or user action to find hotplug devices.

Sending SIGHUP to a running gpsd forces it to close all GPSes and all client connections. It will then attempt to reconnect to any GPSes on its device list and resume listening for client connections. This may be useful if your GPS enters a wedged or confused state but can be soft-reset by pulling down DTR.

When gpsd is called with no initial devices (thus, expecting devices to be passed to it by notifications to the control socket), and reaches a state where there are no devices connected and no subscribers after some devices have been seen, it shuts down gracefully. It is expected that future device hotplug events will reactivate it.

To point gpsd at a device that may be a GPS, write to the control socket a plus sign ('+') followed by the device name followed by LF or CR-LF. Thus, to point the daemon at /dev/foo. send "+/dev/foo\n". To tell the daemon that a device has been disconnected and is no longer available, send a minus sign ('-') followed by the device name followed by LF or CR-LF. Thus, to remove /dev/foo from the search list, send "-/dev/foo\n".

To send a control string to a specified device, write to the control socket a '!', followed by the device name, followed by '=', followed by the control string.

To send a binary control string to a specified device, write to the control socket a '&', followed by the device name, followed by '=', followed by the control string in paired hex digits.

Your client may await a response, which will be a line beginning with either "OK" or "ERROR". An ERROR response to an 'add' command means the device did not emit data recognizable as GPS packets, an ERROR response to a remove command means the specified device was not in gpsd's device pool. An ERROR response to a '!' command means the daemon did not recognize the devicename specified.

The control socket is intended for use by hotplug scripts and other device-discovery services. This control channel is separate from the public gpsd service port, and only locally accessible, in order to prevent remote denial-of-service and spoofing attacks.

## ACCURACY
The base User Estimated Range Error (UERE) of GPSes is 8 meters or less at 66% confidence, 15 meters or less at 95% confidence. Actual horizontal error will be UERE times a dilution factor dependent on current satellite position. Altitude determination is more sensitive to variability in ionospheric signal lag than latitude/longitude is, and is also subject to errors in the estimation of local mean sea level, base error is 12 meters at 66% confidence, 23 meters at 95% confidence. Again, this will be multiplied by a vertical dilution of precision (VDOP) dependent on satellite geometry, and VDOP is typically larger than HDOP. Users should not rely on GPS altitude for life-critical tasks such as landing an airplane.

These errors are intrinsic to the design and physics of the GPS system. gpsd does its internal computations at sufficient accuracy that it will add no measurable position error of its own.

DGPS correction may reduce UERE, provided you are within about 100 miles (160 km) of a DGPS ground station from which you are receiving corrections.

On a 4800bps connection, the time latency of fixes provided by gpsd will be one second or less 95% of the time. Most of this lag is due to the fact that GPSes normally emit fixes once per second, thus expected latency is 0.5sec. On the personal-computer hardware available in 2005 and later, computation lag induced by gpsd will be negligible, on the order of a millisecond. Nevertheless, latency can introduce significant errors for vehicles in motion, at 50 km/h (31 mi/h) of speed over ground, 1 second of lag corresponds to 13.8 meters change in position between updates.

The time reporting of the GPS system itself has an intrinsic accuracy limit of 14 nanoseconds, but this can only be approximated by specialized receivers using that send the high-accuracy PPS (Pulse-Per-Second) over RS232 to cue a clock crystal. Most GPS receivers only report time to a precision of 0.01s or 0.001s, and with no accuracy guarantees below 1sec.

If your GPS uses a SiRF chipset at firmware level 231, reported UTC time may be off by the difference between whatever default leap-second offset has been compiled in and whatever leap-second correction is currently applicable, from startup until complete subframe information is received. Firmware levels 232 and up don’t have this problem. You may run gpsd at debug level 4 to see the chipset type and firmware revision level.

There are exactly two circumstances under which gpsd relies on the host-system clock:

In the GPS broadcast signal, GPS time is represented using a week number that rolls over after 2^10 or 2^13 weeks (about 19.6 years, or 157 years), depending on the spacecraft. Receivers are required to disambiguate this to the correct date, but may have difficulty due to not knowing time to within half this interval, or may have bugs. Users have reported incorrect dates which appear to be due to this issue. gpsd uses the startup time of the daemon detect and compensate for rollovers while it is running, but otherwise reports the date as it is reported by the receiver without attempting to correct it.

If you are using an NMEA-only GPS (that is, not using SiRF or Garmin or Zodiac binary mode), gpsd relies on the system clock to tell it the current century. If the system clock returns an invalid value near zero, and the GPS does not emit GPZDA at the start of its update cycle (which most consumer-grade NMEA GPSes do not) then the century part of the dates gpsd delivers may be wrong. Additionally, near the century turnover, a range of dates as wide in seconds as the accuracy of your system clock may be referred to the wrong century.

## USE WITH NTP
gpsd can provide reference clock information to ntpd or chronyd, to keep the system clock synchronized to the time provided by the GPS receiver.

On Linux, gpsd includes support for interpreting the PPS pulses emitted at the start of every clock second on the carrier-detect lines of some serial GPSes, this pulse can be used to update NTP at much higher accuracy than message time provides. You can determine whether your GPS emits this pulse by running at -D 5 and watching for carrier-detect state change messages in the logfile. In addition, if your kernel provides the RFC 2783 kernel PPS API then gpsd will use that for extra accuracy.

gpsd communicates with ntpd using shared memory segments (SHMs). The SHMs are numbered SHM(0) to SHM(7). and have a name (key) of NTP0 to NTP7. The first local time source on the command line may use NTP0 and NTP1. The second may use NTP2 and NTP3, etc.

You can see the output of gpsd to ntpd in real time with the ntpshmmon command.

Other daemons, such as ptp4l may also be using the same SHMs to talk to ntpd.

Detailed instructions for using GPSD to set up a high-quality time service can be found among the documentation on the GPSD website.

## USE WITH D-BUS
On operating systems that support D-BUS, gpsd can be built to broadcast GPS fixes to D-BUS-aware applications. As D-BUS is still at a pre-1.0 stage, we will not attempt to document this interface here. Read the gpsd source code to learn more.

## SECURITY AND PERMISSIONS ISSUES
gpsd, if given the -G flag, will listen for connections from any reachable host, and then disclose the current position. Before using the -G flag, consider whether you consider your computer’s location to be sensitive data to be kept private or something that you wish to publish.

gpsd must start up as root in order to open the NTPD shared-memory segment, open its logfile, and create its local control socket. Note that starting gpsd with sudo is not the same as starting as root. Before doing any processing of GPS data, it tries to drop root privileges by setting its UID to "nobody" (or another configured userid) and its group ID to the group of the initial GPS passed on the command line — or, if that device doesn’t exist, to the group of /dev/ttyS0.

Privilege-dropping is a hedge against the possibility that carefully crafted data, either presented from a client socket or from a subverted serial device posing as a GPS, could be used to induce misbehavior in the internals of gpsd. It ensures that any such compromises cannot be used for privilege elevation to root.

The assumption behind gpsd's particular behavior is that all the tty devices to which a GPS might be connected are owned by the same non-root group and allow group read/write, though the group may vary because of distribution-specific or local administrative practice. If this assumption is false, gpsd may not be able to open GPS devices in order to read them (such failures will be logged).

In order to fend off inadvertent denial-of-service attacks by port scanners (not to mention deliberate ones), gpsd will time out inactive client connections. Before the client has issued a command that requests a channel assignment, a short timeout (60 seconds) applies. There is no timeout for clients in watcher or raw modes; rather, gpsd drops these clients if they fail to read data long enough for the outbound socket write buffer to fill. Clients with an assigned device in polling mode are subject to a longer timeout (15 minutes).

### CAPABILITIES
If your gpsd was compiled to support capabilities(7), then it may be able to start as a normal user and retain some educed functionality, The following capabilities will be helpful:

Table 2. caps object

Name

Description

CAP_FOWNER

for chmod()

CAP_SETGID

for setgid(), setgroups()

CAP_SETUID

for setuid()

You can set the capabilities by running these commands a root:

```
export CAPS='cap_fowner=ep cap_setgid=ep cap_setuid=ep'
setcap "${CAPS}" [path-to-gpsd]
```

And check the capabilities where set by running this command as a normal user:

```
getcap [path-to-gpsd]
```

## LIMITATIONS
If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences to the same serial device (possible with an RS422 adapter hooked up to some marine-navigation systems), a 'TPV' response may mix an altitude from one device’s GGA with latitude/longitude from another’s RMC/GLL after the second sentence has arrived.

gpsd may change control settings on your GPS (such as the emission frequency of various sentences or packets) and not restore the original settings on exit. This is a result of inadequacies in NMEA and the vendor binary GPS protocols, which often do not give clients any way to query the values of control settings in order to be able to restore them later.

Some receivers do not report VDOP/TDOP/GDOP figures and associated error estimates. In that case they may be computed by gpsd instead. This computation does not exactly match what chips do internally, which includes some satellite weighting using parameters gpsd cannot see.

Autobauding on the Trimble GPSes can take as long as 20 seconds, or more, if the device speed is not matched to the GPS speed. Use the -s option to avoid autobaud delays.

Generation of position error estimates (eph, epv, epd, eps, epc) from the incomplete data handed back by GPS reporting protocols involves both a lot of mathematical black art and fragile device-dependent assumptions. This code has been bug-prone in the past and problems may still lurk there.

AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified.

GPSD presently fully recognizes only the 2.1 level of RTCM2 (message types 1, 3, 4, 5, 6, 7, 9, 16). The 2.3 message types 13, 14, and 31 are recognized and reported. Message types 8, 10-12, 15-27, 28-30 (undefined), 31-37, 38-58 (undefined), and 60-63 are not yet supported.

The ISGPS used for RTCM2 and subframes decoder logic is sufficiently convoluted to confuse some compiler optimizers, notably in GCC 3.x at -O2, into generating bad code.

Devices meant to use PPS for high-precision timekeeping may fail if they are specified after startup by a control-socket command, as opposed to on the daemon’s original command line. Root privileges are dropped early, and some Unix variants require them in order to set the PPS line discipline. Under Linux the POSIX capability to set the line discipline is retained, but other platforms cannot use this code.

USB GPS devices often do not identify themselves through the USB subsystem; they typically present as the class 00h (undefined) or class FFh (vendor-specific) of USB-to-serial adapters. Because of this, the Linux hotplug scripts must tell gpsd to sniff data from every USB-to-serial adapter that goes active and is known to be of a type used in GPSes. No such device is sent configuration strings until after it has been identified as a GPS, and gpsd never opens a device that is opened by another process. But there is a tiny window for non-GPS devices not opened; if the application that wants them loses a race with GPSD its device open will fail and have to be retried after GPSD sniffs the device (normally less than a second later).

## FILES
/dev/ttyS0

Prototype TTY device. After startup, gpsd sets its group ID to the owning group of this device if no GPS device was specified on the command line does not exist.

/etc/gpsd/device-hook

Optional file containing the device activation/deactivation script. Note that while /etc/gpsd is the default system configuration directory, it is possible to build the GPSD source code with different assumptions. See above for further details on the device-hook mechanism.

/@RUNDIR@/chrony.XXX.sock

Optional Unix domain socket provided by chronyd configured with a SOCK reference clock, where XXX is the name of the serial device (e.g. ttyS0). When gpsd is started, it will try to connect to this socket. If connected, it will be sending PPS timing information to chronyd in order to synchronize the system clock.

/@RUNDIR@/chrony.clk.XXX.sock

Similar to chrony.XXX.sock, but will be used to pass timing information to chronyd that is derived from the serial (likely NMEA) timing instead of PPS.

## ENVIRONMENT VARIABLES
By setting the environment variable GPSD_SHM_KEY, you can control the key value used to create the shared-memory segment used for communication with the client library. This will be useful mainly when isolating test instances of gpsd from production ones.

## RETURN VALUES
0

on success.

1

on failure

## APPLICABLE STANDARDS
The official NMEA protocol standards for NMEA0183 and NMEA2000 are available from the National Marine Electronics Association, but are proprietary and expensive; the maintainers of gpsd have made a point of not looking at them. The GPSD project website links to several documents that collect publicly disclosed information about the protocol.

gpsd parses the following NMEA sentences: RMC, GGA, GLL, GSA, GSV, VTG, ZDA, GBS, HDT, DBT, GST. It recognizes these with either the normal GP talker-ID prefix, or with the GN prefix used by GLONASS, or with the II prefix emitted by Seahawk Autohelm marine navigation systems, or with the IN prefix emitted by some Garmin units, or with the EC prefix emitted by ECDIS units, or with the SD prefix emitted by depth sounders, or with the HC and TI prefix emitted by some Airmar equipment. It recognizes some vendor extensions: the PGRME emitted by some Garmin GPS models, the PTNTHTM emitted by True North digital compasses, the PMTK omitted by some San Jose Navigation GPSes, and the PASHR sentences emitted by some Ashtech GPSes.

Note that gpsd JSON returns pure decimal degrees, not the hybrid degree/minute format described in the NMEA standard.

Differential-GPS corrections are conveyed by the RTCM protocols. The applicable standard for RTCM-104 V2 is RTCM Recommended Standards for Differential GNSS (Global Navigation Satellite) Service RTCM Paper 136-2001/SC 104-STD. The applicable standard for RTCM-104 V3 is RTCM Standard 10403.1 for Differential GNSS Services - Version 3 RTCM Paper 177-2006-SC104-STD. Ordering instructions for the RTCM standards are accessible from the website of the Radio Technical Commission for Maritime Services under "Publications".

AIS is defined by ITU Recommendation M.1371, Technical Characteristics for a Universal Shipborne Automatic Identification System Using Time Division Multiple Access. The AIVDM/AIVDO format understood by this program is defined by IEC-PAS 61162-100, Maritime navigation and radiocommunication equipment and systems. A more accessible description of both can be found at AIVDM/AIVDO Protocol Decoding, on the references page of the GPSD project website.

Subframe data is defined by IS-GPS-200, GLOBAL POSITIONING SYSTEM WING (GPSW) SYSTEMS ENGINEERING & INTEGRATION, INTERFACE SPECIFICATION IS-GPS-200. The format understood by this program is defined in Section 20 (Appendix II),

JSON is specified by RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format.

The API for PPS time service is specified by RFC 2783, Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0

The gpsd capabilities follow the proposed, but rescinded POSIX 1e Section 25.2 Capabilities. See capabilities(7).

## AUTHORS
Authors: Eric S. Raymond, Chris Kuethe, Gary Miller. Former authors whose bits have been plowed under by code turnover: Remco Treffcorn, Derrick Brashear, Russ Nelson.

This manual page by Eric S. Raymond <esr@thyrsus.com>.

## SEE ALSO
gpsctl(1), gps(1), gpsprof(1), gpsfake(1). gpscat(1), *ntpshmmon(1),

libgps(3), libgpsmm(3)

gpsd_json(5)

capabilities(7)

chronyd(8), gpsd(8), gpsdctl(8), ntpd(8)

## RESOURCES
Project web site: <https://gpsd.io/> GPSD FAQ: <https://gpsd.io/faq.html> GPSD Time Service HOWTO: <https://gpsd.io/gpsd-time-service-howto.html> Introduction to Time Service: <https://gpsd.io/time-service-intro.html>

## COPYING
This file is Copyright by the GPSD project

SPDX-License-Identifier: BSD-2-clause


gpsdctl

title: gpsdctl(8)

text:
# gpsdctl(8)

## NAME
gpsdctl - tool for sending commands to gpsd over its control socket

## SYNOPSIS
gpsdctl action device

## OPTIONS
action

may be add or remove. If no daemon instance is running when an add is requested, this program will launch one.

device

argument should be the pathname of a device. The device will be opened by gpsd to read sensor data.

## DESCRIPTION
This is a tool for sending an instance of gpsd commands over its control socket to add or remove devices from the daemon’s device list. It is not intended to be called by users, but rather by the Linux hotplug system and similar facilities.

## ENVIRONMENT
Two environment variables are interpreted.

GPSD_SOCKET

sets the location of the control socket. If the effective user ID of this program is root then it usually defaults to /run/gpsd.sock, although some systems may use the deprecated /var/run/gpsd.sock instead. Non-root users will use /tmp/gpsd.sock.

GPSD_OPTIONS

may be a list of options to be passed to gpsd when this tool launches it. It defaults to an empty string.

## RETURN VALUES
0

on success.

1

if the action was unknown or the write to the control socket failed,

## SEE ALSO
gpsd(8), gpsctl(1), gps(1), libgps(3), libgpsmm(3), gpsprof(1), gpsfake(1).

## RESOURCES
Project web site: <https://gpsd.io/>

## COPYING
This file is Copyright 2013 by the GPSD project

SPDX-License-Identifier: BSD-2-clause

## AUTHOR
Eric S. Raymond


gpsinit

title: gpsinit(8)

summary: initialize CAN kernel modules for GPSD

text:
# gpsinit(8)

## NAME
gpsinit - initialize CAN kernel modules for GPSD

## SYNOPSIS
gpsinit [-n control] [-s speed] module_name [interface_name]

gpsinit -h

gpsinit -V

## DESCRIPTION
gpsinit initializes whatever kernel-level modules are needed to enable special non-serial hardware to communicate with a gpsd instance. Note: it will need root permissions to load modules and perform other special operations, such as changing kernel-interface baudrates.

At present, all modes of this tool are concerned with setting up kernel-level interfaces to hardware on a CAN (Control Area Network) speaking NMEA2000.

The program accepts the following options:

-h

Display a brief help text.

-n

Set the CAN network number. The default is 0.

-s

Set the baudrate to be used to communicate over the serial line to the CAN hardware. The default is 38400 baud.

-V

Display the version of gpsinit.

The parameter module_name is mandatory. The socket CAN driver module module_name.ko will be loaded. gpsinit recognize the following module names:

plx_pci, esd_usb2, vcan, slcan

The parameter interface_name and -s speed can used here.

beaglebone

The dcan module needed for the beaglebone is part of the Linux kernel, so no module is loaded in this case.

The parameter interface_name is needed for slcan hardware only. It gives the name of the serial device to which the SL CAN hardware is connected. The default is /dev/ttyUSB0.

## EXAMPLES
All the following examples probably need to be run as root.

gpsinit plx_pci

Attempt to load the module plx_pci and initialize net 0 for the connection to a NMEA2000 network. It will set the baudrate to 250kBits.

gpsinit -n 1 plx_pci

As above, but use net 1.

gpsinit -s 38400 slcan /dev/ttyUSB0

Attempt to load the module slcan and talk to the hardware at 38400 baud connected to port /dev/ttyUSB0.

gpsinit -h

Display a brief help message.

gpsinit -v

Display the version of gpsinit.

## RETURN VALUES
0

on success.

1

on failure

## SEE ALSO
gpsd(8), gps(1)

## RESOURCES
Project web site: <https://gpsd.io/>

## COPYING
This file is Copyright 2013 by the GPSD project

SPDX-License-Identifier: BSD-2-clause

## AUTHOR
Reinhard Arlt