From ffa51b508636bf0f8fa4b994c6f17998eae7e425 Mon Sep 17 00:00:00 2001 From: Nick Logan Date: Wed, 21 Jun 2023 08:40:35 -0500 Subject: [PATCH] Update docs to reference enviroment variable configuration --- conf/GeoIP.env.default | 49 ++++++++++++++++++++++ dev-bin/make-man-pages.pl | 6 +++ doc/GeoIP.conf.md | 42 ++++++++++++------- doc/GeoIP.env.md | 88 +++++++++++++++++++++++++++++++++++++++ doc/geoipupdate.md | 8 ++-- 5 files changed, 176 insertions(+), 17 deletions(-) create mode 100644 conf/GeoIP.env.default create mode 100644 doc/GeoIP.env.md diff --git a/conf/GeoIP.env.default b/conf/GeoIP.env.default new file mode 100644 index 00000000..a6d0a8ac --- /dev/null +++ b/conf/GeoIP.env.default @@ -0,0 +1,49 @@ +# Note that environment variables override any associated config setting from +# a config file. + +# Replace YOUR_ACCOUNT_ID_HERE and YOUR_LICENSE_KEY_HERE with an active account +# ID and license key combination associated with your MaxMind account. These +# are available from https://www.maxmind.com/en/my_license_key. +GEOIPUPDATE_ACCOUNT_ID="YOUR_ACCOUNT_ID_HERE" +GEOIPUPDATE_LICENSE_KEY="YOUR_LICENSE_KEY_HERE" + +# Enter the edition IDs of the databases you would like to update. +# Multiple edition IDs are separated by spaces. +GEOIPUPDATE_EDITION_IDS="GeoLite2-Country GeoLite2-City" + +# The remaining settings are OPTIONAL. + +# The directory to store the database files. Defaults to $DATADIR +# GEOIPUPDATE_DB_DIR="$DATADIR" + +# The server to use. Defaults to "updates.maxmind.com". +# GEOIPUPDATE_HOST="updates.maxmind.com" + +# The proxy host name or IP address. You may optionally specify a +# port number, e.g., 127.0.0.1:8888. If no port number is specified, 1080 +# will be used. +# GEOIPUPDATE_PROXY="127.0.0.1:8888" + +# The user name and password to use with your proxy server. +# GEOIPUPDATE_PROXY_USER_PASSWORD="username:password" + +# Whether to preserve modification times of files downloaded from the server. +# Defaults to "0". +# GEOIPUPDATE_PRESERVE_FILE_TIMES=0 + +# The lock file to use. This ensures only one geoipupdate process can run at a +# time. +# Note: Once created, this lockfile is not removed from the filesystem. +# Defaults to ".geoipupdate.lock" under the $GEOIPUPDATE_DB_DIR. +# GEOIPUPDATE_LOCK_FILE="$GEOIPUPDATE_DB_DIR/.geoipupdate.lock + +# The amount of time to retry for when errors during HTTP transactions are +# encountered. It can be specified as a (possibly fractional) decimal number +# followed by a unit suffix. Valid time units are "ns", "us" (or "µs"), "ms", +# "s", "m", "h". +# Defaults to "5m" (5 minutes). +# GEOIPUPDATE_RETRY_FOR="5m" + +# The number of parallel database downloads. +# Defaults to "1". +# GEOIPUPDATE_PARALLELISM=1 diff --git a/dev-bin/make-man-pages.pl b/dev-bin/make-man-pages.pl index 82acb072..99bcf88b 100755 --- a/dev-bin/make-man-pages.pl +++ b/dev-bin/make-man-pages.pl @@ -19,6 +19,12 @@ sub main { "$build_dir/GeoIP.conf.md", "$build_dir/GeoIP.conf.5", ); + _make_man( + 'GeoIP.env', + 9, + "$build_dir/GeoIP.env.md", + "$build_dir/GeoIP.env.9", + ); return 1; } diff --git a/doc/GeoIP.conf.md b/doc/GeoIP.conf.md index 272997a9..7a61614b 100644 --- a/doc/GeoIP.conf.md +++ b/doc/GeoIP.conf.md @@ -17,66 +17,79 @@ sensitive. `AccountID` -: Your MaxMind account ID. This was formerly known as `UserId`. +: Your MaxMind account ID. This was formerly known as `UserId`. This can be + overridden at run time by the `GEOIPUPDATE_ACCOUNT_ID` environment + variable. `LicenseKey` -: Your case-sensitive MaxMind license key. +: Your case-sensitive MaxMind license key. This can be overriden at run time + by the `GEOIPUPDATE_LICENSE_KEY` environment variables. `EditionIDs` : List of space-separated database edition IDs. Edition IDs may consist of letters, digits, and dashes. For example, `GeoIP2-City` would - download the GeoIP2 City database (`GeoIP2-City`). Note: this was - formerly called `ProductIds`. + download the GeoIP2 City database (`GeoIP2-City`). This can be overridden + at run time by the `GEOIPUPDATE_EDITION_IDS` environment variable. Note: + this was formerly called `ProductIds`. ## Optional settings: `DatabaseDirectory` : The directory to store the database files. If not set, the default is - DATADIR. This can be overridden at run time by the `-d` command line - argument. + DATADIR. This can be overridden at run time by the `GEOIPUPDATE_DB_DIR` + environment variable or the `-d` command line argument. `Host` : The host name of the server to use. The default is `updates.maxmind.com`. + This can be overridden at run time by the `GEOIPUPDATE_HOST` environment + variable. `Proxy` -: The proxy host name or IP address. You may optionally specify - a port number, e.g., `127.0.0.1:8888`. If no port number is specified, - 1080 will be used. +: The proxy host name or IP address. You may optionally specify a port + number, e.g., `127.0.0.1:8888`. If no port number is specified, 1080 + will be used. This can be overridden at run time by the + `GEOIPUPDATE_PROXY` environment variable. `ProxyUserPassword` : The proxy user name and password, separated by a colon. For instance, - `username:password`. + `username:password`. This can be overridden at run time by the + `GEOIPUPDATE_USER_PASSWORD` environment variable. `PreserveFileTimes` : Whether to preserve modification times of files downloaded from the - server. This option is either `0` or `1`. The default is `0`. + server. This option is either `0` or `1`. The default is `0`. This + can be overridden at run time by the `GEOIPUPDATE_PRESERVE_FILE_TIMES` + environment variable. `LockFile` : The lock file to use. This ensures only one `geoipupdate` process can run at a time. Note: Once created, this lockfile is not removed from the filesystem. The default is `.geoipupdate.lock` under the - `DatabaseDirectory`. + `DatabaseDirectory`. This can be overridden at run time by the + `GEOIPUPDATE_LOCK_FILE` environment variable. `RetryFor` : The amount of time to retry for when errors during HTTP transactions are encountered. It can be specified as a (possibly fractional) decimal number followed by a unit suffix. Valid time units are `ns`, `us` (or `µs`), `ms`, - `s`, `m`, `h`. The default is `5m` (5 minutes). + `s`, `m`, `h`. The default is `5m` (5 minutes). This can be overridden at + run time by the `GEOIPUPDATE_RETRY_FOR` environment variable. `Parallelism` : The maximum number of parallel database downloads. The default is 1, which means that databases will be downloaded sequentially. This can be - overriden at runtime by the `--parallelism` command line argument. + overriden at runtime by the `GEOIPUPDATE_PARALLELISM` environment variable + or the `--parallelism` command line argument. ## Deprecated settings: @@ -91,3 +104,4 @@ The following are deprecated and will be ignored if present: # SEE ALSO `geoipupdate`(1) +`GeoIP.env`(9) diff --git a/doc/GeoIP.env.md b/doc/GeoIP.env.md new file mode 100644 index 00000000..cb297842 --- /dev/null +++ b/doc/GeoIP.env.md @@ -0,0 +1,88 @@ +# NAME + +GeoIP.env - Configuration environment variables for geoipupdate + +# SYNOPSIS + +These environment variables allow you to configure your `geoipupdate` +program to download GeoIP2 and GeoLite2 databases. + +# DESCRIPTION + +Environment variables override any associated configuration that may +have been set from the config file. + +## Required settings: + +`GEOIPUPDATE_ACCOUNT_ID` + +: Your MaxMind account ID. This can be overriden at runtime by the +`--parallelism` command line argument. + +`GEOIPUPDATE_LICENSE_KEY` + +: Your case-sensitive MaxMind license key. + +`GEOIPUPDATE_EDITION_IDS` + +: List of space-separated database edition IDs. Edition IDs may consist + of letters, digits, and dashes. For example, `GeoIP2-City` would + download the GeoIP2 City database (`GeoIP2-City`). + +## Optional settings: + +`GEOIPUPDATE_DB_DIR` + +: The directory to store the database files. If not set, the default is + DATADIR. This can be overridden at run time by the `-d` command line + argument. + +`GEOIPUPDATE_HOST` + +: The host name of the server to use. The default is `updates.maxmind.com`. + +`GEOUPUPDATE_PROXY` + +: The proxy host name or IP address. You may optionally specify + a port number, e.g., `127.0.0.1:8888`. If no port number is specified, + 1080 will be used. + +`GEOIPUPDATE_PROXY_USER_PASSWORD` + +: The proxy user name and password, separated by a colon. For instance, + `username:password`. + +`GEOIPUPDATE_PRESERVE_FILE_TIMES` + +: Whether to preserve modification times of files downloaded from the + server. This option is either `0` or `1`. The default is `0`. + +`GEOIPUPDATE_LOCK_FILE` + +: The lock file to use. This ensures only one `geoipupdate` process can run + at a time. Note: Once created, this lockfile is not removed from the + filesystem. The default is `.geoipupdate.lock` under the + `GEOIPUPDATE_DB_DIR`. + +`GEOIPUPDATE_RETRY_FOR` + +: The amount of time to retry for when errors during HTTP transactions are + encountered. It can be specified as a (possibly fractional) decimal number + followed by a unit suffix. Valid time units are `ns`, `us` (or `µs`), `ms`, + `s`, `m`, `h`. The default is `5m` (5 minutes). + +`GEOIPUPDATE_PARALLELISM` + +: The maximum number of parallel database downloads. The default is + 1, which means that databases will be downloaded sequentially. This can be + overriden at runtime by the `--parallelism` command line argument. + +`VERBOSE` + +: Enable verbose mode. Prints out the steps that `geoipupdate` takes. This + can be overriden at runtime by the `--verbose` command line argument. + +# SEE ALSO + +`geoipupdate`(1) +`GeoIP.conf`(5) diff --git a/doc/geoipupdate.md b/doc/geoipupdate.md index 0cc7f0f2..850d8b4f 100644 --- a/doc/geoipupdate.md +++ b/doc/geoipupdate.md @@ -72,9 +72,10 @@ runs `geoipupdate` on each Wednesday at noon: # end of crontab -To use with a proxy server, update your `GeoIP.conf` file as specified -in the `GeoIP.conf` man page or set the `http_proxy` environment -variable. +To use with a proxy server, update your `GeoIP.conf` file as specified in +the `GeoIP.conf` man page or set the `GEOIPUPDATE_PROXY` environment variable +as specified in the `GeoIP.env` man page. Alternatively, set the `http_proxy` +environment variable. # BUGS @@ -97,3 +98,4 @@ to learn more about the GeoIP2 databases or to sign up for a subscription. # SEE ALSO `GeoIP.conf`(5) +`GeoIP.env`(9)