pam_geoip(8)

💖 pam_geoip(8) — the manual, but make it make sense 💖

okay bestie, sit down, hydrate, because we're talking about pam_geoip — the PAM module that checks where in the world your remote user is logging in from. yes, like, geographically. no cap. 🗺️✨

---

🌍 NAME

pam_geoip — GeoIP account management module for (Linux-)PAM

like it's literally in the name bestie, geo + ip, we're doing location vibes inside your PAM stack 🫶

---

✨ SYNOPSIS

account required pam_geoip.so [system_file=file] [geoip_db=file]
       [action=name] [language=name] [debug]

that's it, that's the whole incantation 💅

---

🦋 DESCRIPTION

so the pam_geoip module does one (1) thing and does it gorgeously: it checks whether the remote logged-in user is logging in from a given location. it's giving pam_access(8) energy, except instead of matching host names / IPs it uses a GeoIP2 City or GeoIP2 Country database. glow up fr fr 🌸

the matching happens on given country and city names, or on distance from a given location. and heads up: if you're rocking a country database, then country matching is all you get, that's the whole menu.

this PAM module provides the account hook only. that's the only hook. don't ask for more, she's specialized. 👑

if an IP isn't found in the GeoIP2 database, the location it matches against gets set to "UNKNOWN, *", and obviously no distance matching is possible for those, like, how would you even. 💀

and here's a cute lil twist: if a file named /etc/security/geoip.SERVICE.conf can be opened (with SERVICE being the name of the PAM service), that one gets used instead of the default /etc/security/geoip.conf. sneaky. iconic. ✨

the first matching entry in the geoip.conf(5) file wins — like first come first served at a sample sale — so the action given in that line is what gets returned to PAM:

• allow — returns PAM_SUCCESS
• deny — returns PAM_PERM_DENIED
• ignore — returns PAM_IGNORE

---

🎀 OPTIONS

these options may be given in the PAM config file as parameters:

• system_file=/path/to/geoip.conf — the configuration file for pam_geoip. default is /etc/security/geoip.conf. for the format of this file, go read geoip.conf(5).

NOTE: when a file /etc/security/geoip.SERVICE.conf file is present, this switch is ignored (with "SERVICE" being the name of the PAM service, e.g. "sshd"). so like, don't be shocked when your system_file just gets ghosted. 🙈

• geoip_db=/path/to/GeoLite2-City.mmdb — the GeoIP2 database to use. default: /usr/share/GeoIP/GeoLite2-City.mmdb. this must be a "GeoIP2 City Edition" or a "GeoIP2 Country Edition" file, see <https://www.maxmind.com/en/geoip2-databases> and <https://dev.maxmind.com/geoip/geoip2/geolite2/> for more information. no knockoff databases pls, she can tell. 👀

the database can contain IPv4 or IPv6 addresses or both. multitasking queen. 🌈

• action=ACTION — sets the default action if no location matches. default is "deny". other possible values are "allow" or "ignore". for the meanings of these, see above (scroll up bestie, we literally just did this). ⬆️
• language=NAME — sets the language to be used to find names (city etc.). default is "en". 🌐
• debug — adds some debugging output to syslog. for when you need to know why, and honestly same. 🔍

---

📁 FILES

• /etc/security/geoip.conf — the default configuration file for this module
• /etc/security/geoip.SERVICE.conf — the default configuration file for PAM service SERVICE
• /etc/pam.d/* — the PAM(7) configuration files

---

👀 SEE ALSO

geoip.conf(5), pam_access(8), pam.d(5), pam(7)

like go read those too, they're the supporting cast and they ate 💅

---

🫶 AUTHOR

Amish — GeoIP2 Hanno Hecker — Legacy GeoIP "<vetinari@ankh-morp.org>"

---

and that's the whole page bestie!! this version is from 2024-02-05, and it belongs to the pam_geoip(8) manual — so if you ever forget where you read all this, it's literally right there in the footer, periodt. 💖✨🎀