diff mbox series

man: Add manual page for `location-importer`

Message ID 20260712084614.126348-1-valter.jansons@gmail.com
State Accepted
Commit b206dcfe22e127750b33262b2aca1053829a6e37
Headers
Series man: Add manual page for `location-importer` |

Commit Message

Valters Jansons 12 Jul 2026, 8:46 a.m. UTC 
Currently, the `location-importer` binary gets installed without
a manual page. It's expected that all tools installed get manpages.

This commit proposes a generated manpage, introspecting the script's
handlers and considering the structure of the other existing AsciiDoc
files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Valters Jansons <valter.jansons@gmail.com>
---
 Makefile.am               |   3 +-
 man/location-importer.txt | 116 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+), 1 deletion(-)
 create mode 100644 man/location-importer.txt
diff mbox series

Patch

diff --git a/Makefile.am b/Makefile.am
index 93c5aad..0d03238 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -566,7 +566,8 @@  MANPAGES_3 = \
 	man/loc_set_log_priority.3
 
 MANPAGES_1 = \
-	man/location.1
+	man/location.1 \
+	man/location-importer.1
 
 MANPAGES_TXT   = $(MANPAGES_TXT_3) $(MANPAGES_TXT_1)
 MANPAGES_TXT_3 = $(patsubst %.3,%.txt,$(MANPAGES_3))
diff --git a/man/location-importer.txt b/man/location-importer.txt
new file mode 100644
index 0000000..283a466
--- /dev/null
+++ b/man/location-importer.txt
@@ -0,0 +1,116 @@ 
+= location-importer(1)
+
+== NAME
+location-importer - Fill the location database with data
+
+== SYNOPSIS
+[verse]
+`location-importer write [--signing-key=FILE] [--backup-signing-key=FILE] [--vendor=VENDOR] [--description=DESCRIPTION] [--license=LICENSE] [--version=VERSION] FILE`
+`location-importer update-whois [SOURCE ...]`
+`location-importer update-announcements SERVER`
+`location-importer update-geofeeds`
+`location-importer update-feeds [FEED ...]`
+`location-importer update-overrides FILE ...`
+`location-importer import-countries FILE`
+
+== DESCRIPTION
+`location-importer` collects location data from various public sources
+(the WHOIS databases of the Regional Internet Registries, BGP announcements,
+geofeeds, and third-party feeds) and stores it in a PostgreSQL database.
+From there, it compiles a database file in libloc format which can be
+queried with location(1).
+
+== OPTIONS
+
+--database-host HOST::
+--database-name NAME::
+--database-username USERNAME::
+--database-password PASSWORD::
+	The connection parameters for the PostgreSQL database which stores any
+	intermediate data.
+	+
+	These options are required for every command.
+
+--quiet::
+	Enable quiet mode
+
+--debug::
+	Enable debugging mode
+
+== COMMANDS
+
+'write [--signing-key=FILE] [--backup-signing-key=FILE] [--vendor=VENDOR] [--description=DESCRIPTION] [--license=LICENSE] [--version=VERSION] FILE'::
+	This command compiles a database in libloc format out of the contents
+	of the PostgreSQL database and writes it to the given file.
+	+
+	The database can be signed with the key given with '--signing-key'.
+	A second key can be given with '--backup-signing-key' to allow rolling
+	over to it at a later point.
+	+
+	The '--vendor', '--description' and '--license' parameters set the
+	metadata of the database, and '--version' selects the database format
+	version.
+
+'update-whois [SOURCE ...]'::
+	This command downloads and imports WHOIS data from the Regional
+	Internet Registries (AFRINIC, APNIC, ARIN, JPNIC, LACNIC, RIPE).
+	+
+	If one or more SOURCE arguments are given, only these sources will be
+	updated.
+	+
+	Countries have to be imported with 'import-countries' before any WHOIS
+	data can be imported.
+
+'update-announcements SERVER'::
+	This command imports announced prefixes from a BGP route server.
+	+
+	SERVER is the path to the UNIX domain socket of a locally running Bird
+	instance.
+	+
+	Any unroutable address space (e.g. RFC 1918, loopback, or link-local
+	networks) is filtered out.
+
+'update-geofeeds'::
+	This command refreshes all geofeeds (RFC 8805) which are referenced in
+	the database.
+
+'update-feeds [FEED ...]'::
+	This command updates data from third-party feeds, currently the AWS IP
+	ranges as well as the Spamhaus DROP and ASN-DROP lists.
+	+
+	If one or more FEED arguments are given, only these feeds will be
+	updated.
+
+'update-overrides FILE ...'::
+	This command imports override files which manually correct or amend
+	network and Autonomous System data.
+	+
+	Any previously imported overrides will be replaced.
+
+'import-countries FILE'::
+	This command imports the list of countries from the given file which
+	contains one country per line consisting of the country code, the
+	continent code and the name.
+	+
+	Any previously imported countries will be replaced.
+
+'--help'::
+	Shows a short help text on using this program.
+
+'--version'::
+	Shows the program's version and exits.
+
+== EXIT CODES
+The 'location-importer' 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.
+
+== SEE ALSO
+link:location[1]
+
+== BUG REPORTS
+Please report all bugs to the bugtracker at https://bugzilla.ipfire.org/;
+refer to https://wiki.ipfire.org/devel/bugzilla for details.
+
+== AUTHORS
+Michael Tremer