'\" t
.\"     Title: location
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/10/2024
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "LOCATION" "1" "" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
location \- Query the location database
.SH "SYNOPSIS"
.sp
.nf
location export \-\-directory=DIR [\-\-format=FORMAT] [\-\-family=ipv6|ipv4] [ASN|CC \&.\&.\&.]
location get\-as ASN [ASN\&.\&.\&.]
location list\-countries [\-\-show\-name] [\-\-show\-continent]
location list\-networks\-by\-as ASN
location list\-networks\-by\-cc COUNTRY_CODE
location list\-networks\-by\-flags [\-\-anonymous\-proxy|\-\-satellite\-provider|\-\-anycast|\-\-drop]
location lookup ADDRESS [ADDRESS\&.\&.\&.]
location search\-as STRING
location update [\-\-cron=daily|weekly|monthly]
location verify
location version
.fi
.SH "DESCRIPTION"
.sp
location retrieves information from the location database\&. This data can be used to determine someone\(cqs location on the Internet and for building firewall rulesets to block access from certain ASes or countries\&.
.SH "OPTIONS"
.PP
\-\-database FILE, \-d FILE
.RS 4
The path of the database which is being opened\&.

If this option is omitted, the system\(cqs database will be opened\&.
.RE
.PP
\-\-quiet
.RS 4
Enable quiet mode
.RE
.PP
\-\-debug
.RS 4
Enable debugging mode
.RE
.SH "COMMANDS"
.PP
\fIexport [\-\-directory=DIR] [\-\-format=FORMAT] [\-\-family=ipv6|ipv4] [ASN|CC \&...]\fR
.RS 4
This command exports the whole database into the given directory\&.

The output can be filtered by only exporting a certain address family, or by passing a list of country codes and/or ASNs\&. The default is to export all known countries\&.

The output format can be chosen with the
\fI\-\-format\fR
parameter\&. For possible formats, please see below\&.

If the
\fI\-\-directory\fR
option is omitted, the output will be written to stdout which is useful when you want to load any custom exports straight into nftables or ipset\&.
.RE
.PP
\fIget\-as ASN [ASN\&...]\fR
.RS 4
This command returns the name of the owning organisation of the Autonomous System\&.
.RE
.PP
\fIlist\-countries [\-\-show\-name] [\-\-show\-continent]\fR
.RS 4
Lists all countries known to the database\&.

With the optional parameters
\fI\-\-show\-name\fR
and
\fI\-\-show\-continent\fR, the name and continent code will be printed, too\&.
.RE
.PP
\fIlist\-networks\-by\-as [\-\-family=[ipv6|ipv4]]\ \&[\-\-format=FORMAT]\ \&ASN\fR
.RS 4
Lists all networks which belong to this Autonomous System\&.

The
\fI\-\-family\fR
parameter can be used to filter output to only IPv6 or IPv4 addresses\&.

The
\fI\-\-format\fR
parameter can change the output so that it can be directly loaded into other software\&. For details see below\&.
.RE
.PP
\fIlist\-networks\-by\-cc [\-\-family=[ipv6|ipv4]]\ \&[\-\-format=FORMAT] COUNTRY_CODE\fR
.RS 4
Lists all networks that belong to a country\&.

The country has to be encoded in ISO3166 Alpha\-2 notation\&.

See above for usage of the
\fI\-\-family\fR
and
\fI\-\-format\fR
parameters\&.
.RE
.PP
\fIlist\-networks\-by\-flags [\-\-family=[ipv6|ipv4]]\ \&[\-\-format=FORMAT] [\-\-anonymous\-proxy|\-\-satellite\-provider|\-\-anycast|\-\-drop]\fR
.RS 4
Lists all networks that have a certain flag\&.

See above for usage of the
\fI\-\-family\fR
and
\fI\-\-format\fR
parameters\&.
.RE
.PP
\fIlist\-bogons [\-\-family=[ipv6|ipv4]] [\-\-format=FORMAT]\fR
.RS 4
Lists all bogons (i\&.e\&. networks that are unknown to the database)\&.

See above for usage of the
\fI\-\-family\fR
and
\fI\-\-format\fR
parameters\&.
.RE
.PP
\fIlookup ADDRESS [ADDRESS\&...]\fR
.RS 4
This command returns the network the given IP address has been found in as well as its Autonomous System if that information is available\&.
.RE
.PP
\fIsearch\-as STRING\fR
.RS 4
Lists all Autonomous Systems which match the given string\&.

The search will be performed case\-insensitively\&.
.RE
.PP
\fIupdate\fR
.RS 4
This command will try to update the local database\&.

It will terminate with a return code of zero if the database has been successfully updated\&. 1 on error, 2 on invalid call and 3 if the database was already the latest version\&.

The
\fI\-\-cron\fR
option allows limiting updates to once a day (\fIdaily\fR), once a week (\fIweekly\fR), or once a month (\fImonthly\fR)\&. If the task is being called, but the database has been updated recently, an update will be skipped\&.
.RE
.PP
\fIverify\fR
.RS 4
Verifies the downloaded database\&.
.RE
.PP
\fIversion\fR
.RS 4
Shows the version information of the downloaded database\&.
.RE
.PP
\fI\-\-help\fR
.RS 4
Shows a short help text on using this program\&.
.RE
.PP
\fI\-\-version\fR
.RS 4
Shows the program\(cqs version and exists\&.
.RE
.SH "EXIT CODES"
.sp
The \fIlocation\fR command will normally exit with code zero\&. If there has been a problem and the requested action could not be performed, the exit code is unequal to zero\&.
.SH "FORMATS"
.sp
Some commands allow specifying the output format\&. This is helpful if the exported data should be imported into a packet filter for example\&. The following formats are understood:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIlist\fR
(default): Just lists all networks, one per line
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIipset\fR: For ipset
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fInftables\fR: For nftables
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIxt_geoip\fR: Returns a list of networks to be loaded into the xt_geoip kernel module
.RE
.SH "HOW IT WORKS"
.sp
The downloader checks a DNS record for the latest version of the database\&. It will then try to download a file with that version from a mirror server\&. If the downloaded file is outdated, the next mirror will be tried until we have found a file that is recent enough\&.
.SH "BUG REPORTS"
.sp
Please report all bugs to the bugtracker at \m[blue]\fBhttps://bugzilla\&.ipfire\&.org/\fR\m[]; refer to \m[blue]\fBhttps://wiki\&.ipfire\&.org/devel/bugzilla\fR\m[] for details\&.
.SH "AUTHORS"
.sp
Michael Tremer