.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "pam_geoip 8"
.TH pam_geoip 8 2024-02-05 " " " "
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
pam_geoip \- GeoIP account management module for (Linux\-)PAM
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& account required pam_geoip.so [system_file=file] [geoip_db=file]
\&        [action=name] [language=name] [debug]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBpam_geoip\fR module provides a check if the remote logged in user is
logged in from a given location. This is similar to \fBpam_access\fR\|(8), but
uses a GeoIP2 City or GeoIP2 Country database instead of
host name / IP matching.
.PP
The matching is done on given country and city names or on distance from
a given location. With a country database only matches of the countries are
possible.
.PP
This PAM module provides the \fIaccount\fR hook only.
.PP
If an IP is not found in the GeoIP2 database, the location to match against
is set to \f(CW\*(C`UNKNOWN, *\*(C'\fR, no distance matching is possible for these,
of course.
.PP
If a file named \fI/etc/security/geoip.SERVICE.conf\fR (with SERVICE being the
name of the PAM service) can be opened, this is used instead of the default
\&\fI/etc/security/geoip.conf\fR.
.PP
The first matching entry in the \fBgeoip.conf\fR\|(5) file wins, i.e. the action
given in this line will be returned to PAM:
.IP allow 4
.IX Item "allow"
PAM_SUCCESS
.IP deny 4
.IX Item "deny"
PAM_PERM_DENIED
.IP ignore 4
.IX Item "ignore"
PAM_IGNORE
.SH OPTIONS
.IX Header "OPTIONS"
These options may be given in the PAM config file as parameters:
.IP system_file=/path/to/geoip.conf 4
.IX Item "system_file=/path/to/geoip.conf"
The configuration file for \fBpam_geoip\fR. Default is
\&\fI/etc/security/geoip.conf\fR. For the format of this file, see \fBgeoip.conf\fR\|(5).
.Sp
\&\fBNOTE\fR: when a file \fI/etc/security/geoip.SERVICE.conf\fR file is present, this
switch is ignored (with \f(CW\*(C`SERVICE\*(C'\fR being the name of the PAM service, e.g.
\&\f(CW\*(C`sshd\*(C'\fR).
.IP geoip_db=/path/to/GeoLite2\-City.mmdb 4
.IX Item "geoip_db=/path/to/GeoLite2-City.mmdb"
The GeoIP2 database to use. Default: \fI/usr/share/GeoIP/GeoLite2\-City.mmdb\fR.
This must be a \f(CW\*(C`GeoIP2 City Edition\*(C'\fR or a \f(CW\*(C`GeoIP2 Country Edition\*(C'\fR file, see
<https://www.maxmind.com/en/geoip2\-databases> and
<https://dev.maxmind.com/geoip/geoip2/geolite2/> for more information.
.Sp
The database can contain IPv4 or IPv6 addresses or both.
.IP action=ACTION 4
.IX Item "action=ACTION"
Sets the default action if no location matches. Default is \f(CW\*(C`deny\*(C'\fR. Other
possible values are \f(CW\*(C`allow\*(C'\fR or \f(CW\*(C`ignore\*(C'\fR. For the meanigns of these, see
above.
.IP language=NAME 4
.IX Item "language=NAME"
Sets the language to be used to find names (city etc.). Default is \f(CW\*(C`en\*(C'\fR.
.IP debug 4
.IX Item "debug"
Adds some debugging output to syslog.
.SH FILES
.IX Header "FILES"
.IP /etc/security/geoip.conf 4
.IX Item "/etc/security/geoip.conf"
The default configuration file for this module
.IP /etc/security/geoip.SERVICE.conf 4
.IX Item "/etc/security/geoip.SERVICE.conf"
The default configuration file for PAM service SERVICE
.IP /etc/pam.d/* 4
.IX Item "/etc/pam.d/*"
The \fBPAM\fR\|(7) configuration files
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgeoip.conf\fR\|(5), \fBpam_access\fR\|(8), \fBpam.d\fR\|(5), \fBpam\fR\|(7)
.SH AUTHOR
.IX Header "AUTHOR"
Amish \- GeoIP2
Hanno Hecker \- Legacy GeoIP \f(CW\*(C`<vetinari@ankh\-morp.org>\*(C'\fR