GEOCLUE(5)

💖 GEOCLUE CONFIGURATION — okay bestie, let's get you configured 💖

hi hi hiii 🫶 you've stumbled into the File Formats Manual, section 5, and honestly? iconic. this is the whole vibe of GeoClue's config files. no cap, read all of it, it's not even that long. 💅

---

✨ NAME ✨

geoclue.conf — geoclue configuration parameters 🌸

---

🌈 SYNOPSIS 🌈

Main configuration file:

/etc/geoclue/geoclue.conf

Overwriting parameters files:

/etc/geoclue/conf.d

---

💜 DESCRIPTION 💜

so the main GeoClue config file, geoclue.conf, is the one that specifies the parameters that control how geoclue operates. it's giving main character energy, but it doesn't have to do it alone. 🎀

you can overwrite parameters by dropping configuration files into the conf.d directory, and they get applied in alphabetic order. so like, a config file called 90-config.conf will overwrite parameters specified in another config file called 50-config.conf in the conf.d directory. numbers are doing the sorting, bestie, not vibes. 🔥

every single configuration setting down below is mandatory, and the defaults are literally just what you see before you edit them in geoclue.conf. so if you want to keep the default values around (smart, queen behavior 👑), copy and comment out the appropriate line(s) before you change them.

also important: a missing enable key for a particular source in the main configuration file causes that source to be enabled by default. adding an enable key setting to any further config file can overwrite this default. so like, silence = yes in this house. 💀

---

🦋 AGENT CONFIGURATION OPTIONS 🦋

[agent] is used to begin the agent configuration. cute little header, right? 💖

• whitelist — the whitelist of desktop IDs (without the .desktop part, bestie, don't add it) of all agents we recognise, separated by a ;. periodt.

whitelist=geoclue-demo-agent;gnome-
shell;io.elementary.desktop.agent-geoclue2

---

🌸 LOCATION SOURCE CONFIGURATION OPTIONS 🌸

🧚 [ip]

IP source configuration options ✨

enable=true

Enable the GeoIP source.

method=ichnaea

Method (backend) to use for IP location. Currently implemented are:

• "ichnaea": Use the Ichnaea API with the URL from the wifi source.
• "gmaps": Use the location determined by Google Maps.
• "reallyfreegeoip": reallyfreegeoip.org. This API does not return accuracy, so we use a constant value. See the accuracy option below.

The following options do not need to be set, but can be provided if you want to override the method defaults:

url=https://example.com/v1/geolocate

Alternative URL to the GeoIP service implemented by the selected method.

accuracy=30000.0

Override the accuracy received from the GeoIP server (or hardcoded into the method) with this value. 💅

---

🛰️ [network-nmea]

Network NMEA source configuration options 💫

Network NMEA sources are automatically discovered using avahi, domain "_nmea-0183._tcp". An NMEA service in your network can be registered to avahi by running:

$ avahi-publish-service -H my.nmea.host "NMEA over TCP" _nmea-0183._tcp 50000

Here 'my.nmea.host' and '50000' are the hostname and port of the NMEA service. 🫶

enable=true

Fetch location from NMEA sources on local network?

nmea-socket=/var/run/gps-share.sock

Use a unix socket as the NMEA data source. If not set, unix socket will not be used. ngl that default is doing nothing and that's fine. 💀

---

📡 [3g]

3G source configuration options 🌈

enable=true

Enable 3G source. The 3G source uses the wireless geolocation service URL defined in the "wifi" section. iykyk, it borrows the wifi section's fit. ✨

---

📶 [cdma]

CDMA source configuration options 🎀

enable=true

Enable CDMA source.

---

🛰️ [modem-gps]

Modem GPS source configuration options 💖

enable=true

Enable Modem-GPS source.

---

📶 [wifi]

WiFi source configuration options 🔥

enable=true

Enable WiFi source.

url=https://example.com/v1/geolocate?key=YOUR_KEY

URL to wireless geolocation service compatible with the Ichnaea API (https://ichnaea.readthedocs.io/en/latest/api/geolocate.html). If not set, defaults to an URL set in the build configuration. If an URL is not set here or in the build configuration, the wifi and 3g sources will be disabled. An API key can be set with the "key" URL parameter. 🔑

submit-data=false

Submit data to a wireless geolocation service. If set to true, geoclue will automatically submit network data to a wireless geolocation service each time it gets a GPS lock. Currently, only Modem-GPS or Network NMEA sources are supported as providers of a location to submit (one at a time). If Modem-GPS source is enabled above it will be the exclusive provider (regardless whether the system is actually equipped with such modem), otherwise Network NMEA source will be considered. so like, one at a time, no polyamory here. 💅

submission-url=https://example.com/v2/geosubmit?key=YOUR_KEY

URL to submit data to a wireless geolocation service with an Ichnaea compatible API (https://ichnaea.readthedocs.io/en/latest/api/geosubmit2.html).

submission-nick=geoclue

A nickname to submit network data with. Sets an "X-Nickname" HTTP header to the submit request. If set to an empty string, omitted from the submission. Otherwise, must be 2 to 32 characters long. Defaults to "geoclue". pick a cute name bestie, but stay in the character limit. 🎀

---

🧭 [compass]

Compass configuration options ⭐

enable=true

Enable Compass.

---

📍 [static-source]

Static source configuration options. This source reads location from "geolocation" file in /etc. See "STATIC LOCATION FILE" below for the format of this file. While this file is constantly monitored for changes during geoclue operation, and the reported static location is updated accordingly, this source isn't meant for inputting a dynamically changing location to geoclue (please use the Network NMEA source for that). no cap, that's not what it's for, use the right source bestie. 🙈

enable=true

Enable the static source. If you make use of this source, you probably should disable other location sources in geoclue.conf so they won't override the configured static location. 👑

---

👑 APPLICATION CONFIGURATION OPTIONS 👑

Having an entry here for an application with allowed=true means that geoclue will not ask an agent to authorize the application. This is to ensure that applications with built-in authorization mechanism (e.g web browsers) do not have to be bound to agents. slay, they handle their own business. 💅

If your application is denied access to location information and your operating system doesn't provide any mechanism to change that, it is likely a bug in your operation system (or geoclue). The solution is to report the issue with all details, rather than adding your application to this list. fr fr, don't just sneak yourself onto the list, that's not it. 😭

Format:

[random-app]

Desktop ID of application without .desktop part.

allowed=true|false

Allowed access to location information?

system=true|false

Is application a system component?

users=

List of UIDs of all users for which this application is allowed location info access, separated by ';'. Keep it empty for allowing it for all users. 🫶

Examples:

[gnome-datetime-panel]
allowed=true
system=true
users=

[gnome-color-panel]
allowed=true
system=true
users=

[org.gnome.Shell]
allowed=true
system=true
users=

[io.elementary.desktop.agent-geoclue2]
allowed=true
system=true
users=

[epiphany]
allowed=true
system=false
users=

[firefox]
allowed=true
system=false
users=

look at them go, all lined up and thriving. 🌈

---

📍 STATIC LOCATION FILE 📍

🎀 Basic format:

The static location file in /etc (used by the static source) is a text file consisting of the following:

1. Latitude (floating point number; positive values mean north, negative south)
2. Longitude (floating point number; positive values mean east, negative west)
3. Altitude (floating point number; in meters)
4. Accuracy radius (floating point number; in meters)

These values need to be separated by newline characters. one per line, bestie, don't get creative. 💅

🌸 Additional format information:

• The '#' character starts a comment, which continues until the end of the current line.
• Leading and trailing white-space on each line is ignored.
• Empty lines (or containing just white-space or a comment) are ignored.

✨ Example:

# Example static location file for a machine inside Statue of Liberty torch

40.6893129   # latitude
-74.0445531  # longitude
96           # altitude
1.83         # accuracy radius (the diameter of the torch is 12 feet)

the torch diameter lore is genuinely sending me 😭🔥

🔒 Notes:

For extra security, the static location file can be made readable just by the geoclue user:

# chown geoclue /etc/geolocation
# chmod 600 /etc/geolocation

lock it down bestie, nobody else needs to read your coordinates. 🔐

---

🫶 CLIENT LIST 🫶

Sending SIGUSR1 to a running geoclue process prints the current list of clients to the log. that's it, that's the whole section, and it ate. 💖

---

💜 AUTHOR 💜

Sachin Chand

---

okay that's the whole page, you made it, I'm so proud of you 🥹✨ this was the GeoClue Configuration page, section 5, hanging out in the File Formats Manual — and that footer line you saw, GEOCLUE CONFIGURATION(5), is just this page's source/version tag signing off. no date on it, so nothing to report there, bestie. go configure something iconic. 💅🎀🦋