Package: nfsn-ddns
NearlyFreeSpeech.net Dynamic DNS UtilityOverviewThe following provides a utility to update aNearlyFreeSpeech.NETDNS record with a dynamic IP address. Invoking this utility will perform the
following:Selecting a random provider to query for a public IP of the running host.Query a NearlyFreeSpeech.NET domain for a configured IP on aArecord.Compare the address, and update if they do not match.(optional)Cache the detected public address set on NearlyFreeSpeech.NET
for a couple of days (configurable) to limit API requests.RequirementsPython3.8+PyYAMLRequests2.30.0+InstallationThis tool can be installed usingpip:pipinstallnfsn-ddns(or)python-mpipinstallnfsn-ddnsUsageThis tool can be invoked from a command line using:nfsn-ddns--help(or)python-mnfsn-ddns--helpConfigurationThis utility can be configured using a file, command line arguments or
environment variables. An example configuration file (config.yaml) is
as follows:nfsn-ddns:
  api-login: <api-login>
  api-token: <api-token>
  domains:
    - <domain>
  timeout: 10A user can use a combination of ways to configure this utility. For example,
most options can be configured from the command line, but some options (such
as the API token) can be configured from an environment variable:export NFSN_DDNS_API_TOKEN=myapitoken
nfsn-ddns --api-login myaccount --ddns-domain ddns.example.comAll available configuration options are listed as follows:Essential OptionsAPI LoginThe login/account of the NearlyFreeSpeech.NET user. This is used to
authenticate API requests.Command line option:--api-loginConfiguration key:api-login(str)Environment variable:NFSN_DDNS_API_LOGINAPI TokenThe token to use when authenticating API requests. Members can acquire an
API token by viewing their profiles and selectingManage API Key. In this
page, users can request to generate an API token.Command line option:--api-tokenConfiguration key:api-token(str)Environment variable:NFSN_DDNS_API_TOKENDDNS DomainsThe DNS resource to update, which includes the DNS record which to update
with a dynamically detected IP address, along with its domain. For example:ddns.example.comMultiple domains can be provided, for users who want a DDNS record across
multiple domains (although the use of CNAME's are recommended when attempting
to updated multiple records for a single domain).Command line option:--ddns-domainConfiguration key:domains(str-list)Environment variable:NFSN_DDNS_DOMAINS(;-separated)Additional OptionsCacheConfigure whether a detected public IP will be cached into a local file.
his feature can be used to avoid NFSN API calls if it is believed the
public IP of a host is believed to have not changed. After a successful
verification of a configured DNS record, the detected public IP can be
stored in a cache file for future considerations. Next time this utility
runs and detects a public IP address, if the address matches that of the
cached file, no API requests to NFSN will be made. The cache will be
considered a valid source of information for configured number of days
(see "Cache Days").By default, this setting is not enabled (except in container environments).Command line option:--cacheConfiguration key:cache(bool)Environment variable:NFSN_DDNS_CACHECache DaysWhen using the cache capability, this value configures the total number of
days before the cache is considered to be stale. A stale cache will cause
this utility to perform an API request with NFSN to verify the DNS record
matches.By default, a cache is considered valid for seven (7) days.Command line option:--cache-daysConfiguration key:cache-days(int)Environment variable:NFSN_DDNS_CACHE_DAYSCache FileWhen using the cache capability, the specific file where cached content
is stored if set by this option.By default, the cache file location used will be the first available path
that is writable by this utility:/run/nfsn-ddns/cached-ip
 (or)
/run/user/(UID)/cached-ip
 (or)
nfsn-ddns-cached-ipCommand line option:--cache-fileConfiguration key:cache-fileEnvironment variable:NFSN_DDNS_CACHE_FILEIP API EndpointsIP API endpoints are web services used to help determine the public IP
address of the instance running this utility. The detected IP will be used
to update the configured DNS record.The endpoint used is chosen at random each run. If a given endpoint cannot
be accessed, other endpoints are used until an IP address is provided or
all endpoints have been exhausted.The default endpoints used are as follows:https://api.ipify.orghttps://checkip.amazonaws.com/https://ifconfig.me/iphttps://ipinfo.io/iphttps://trackip.net/ipUsers can override what endpoints to use by configuring this option.Configuration key:myip-api-endpoints(str-list)Environment variable:NFSN_DDNS_MYIP_API_ENDPOINTS(;-separated)TimeoutConfigures the timeout (in seconds) until any requests to external sources
(i.e. NFSN API or IP providers) are considered timed out. The default
timeout for all requests is configured to ten (10) seconds.Command line option:--timeoutConfiguration key:timeoutEnvironment variable:NFSN_DDNS_TIMEOUTAdvanced OptionsNFSN API EndpointThe API endpoint for NearlyFreeSpeech.NET. In almost all cases, this
option never needs to be changed. However, the option is provided if a
use case requires a different endpoint to be used.This value is configured tohttps://api.nearlyfreespeech.net/dnsby
default.Configuration key:nfsn-api-endpoint(str)Environment variable:NFSN_DDNS_NFSN_API_ENDPOINTDockerThis project supports multiple ways to use this utility inside a Docker
environment. A recommended choice is to use a pre-built image available
from GitHub's container registry.Pre-built imageA pre-built image can be acquired using the following command:docker pull ghcr.io/jdknight/nfsn-ddnsPrepare a configuration environment for this container by creating a
file/etc/nfsn-ddnswith the contents defined inenv.default(users can use any path or filename they desire, as long as the followingdocker runcommand points to this file). Adjust these options to the
configuration desired.The container than can be run using the following command:docker run --name nfsn-ddns --detach --restart unless-stopped \
    --env-file /etc/nfsn-ddns ghcr.io/jdknight/nfsn-ddnsSelf-built imageUsers who wish to manage their own image can do so with the Docker
definitions found inside this repository. This can be done by cloning
this repository on the host wanting to run the container. A Docker
build can be run on thedocker build -t ghcr.io/jdknight/nfsn-ddns --detach -f docker/Dockerfile .Then running the samedocker runcall mentioned above.Self-managed Docker ComposeUsers can also take advantage of the Docker compose definition. First, copy
the environment template (env.default) to.nfsn-ddns.env, followed by
editing required options.cp env.default .nfsn-ddns.envNext, load up the container usingdocker compose:docker compose build
docker compose up --detachBoth Docker build calls will by default load a container with the
PyPI version of nfsn-ddns. Users wanting to use the local implementation
in their container can do so by performing a Docker build with the--build-arg localargument.For example:docker compose build --build-arg BUILD_MODE=local
docker compose up --detach