NearlyFreeSpeech.net Dynamic DNS Utility
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
NearlyFreeSpeech.net Dynamic DNS Utility
Overview
The following provides a utility to update a NearlyFreeSpeech.NET DNS record with a dynamic IP address. The default process when 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 API for a configured IP on DNS record.
- 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.
Requirements
Installation
This tool can be installed using pip:
pip install nfsn-ddns
(or)
python -m pip install nfsn-ddns
Usage
This tool can be invoked from a command line using:
nfsn-ddns --help
(or)
python -m nfsn-ddns --help
Configuration
This 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: 10
A 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.com
All available configuration options are listed as follows:
| Essential Options | |
|---|---|
| API Login |
The login/account of the NearlyFreeSpeech.NET user. This is used to authenticate API requests.
|
| API Token |
The token to use when authenticating API requests. Members can acquire an
API token by viewing their profiles and selecting
|
| DDNS Domains |
The DNS resource to update, which includes the DNS record which to update with a dynamically detected IP address, along with its domain. For example: Multiple 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).
|
| Additional Options | |
| Cache |
Configure 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).
|
| Cache Days |
When 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 (
|
| Cache File |
When 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:
|
| IPv4 |
Configure whether this utility will attempt to determine an IPv4 address
and attempt to configure an By default, this setting is enabled.
|
| IPv4 API Endpoint Command |
Configures a command to invoke when attempting to fetch the IPv4 address of
the instance running this utility. The returned IP will be used to update
the configured DNS Users can configure the command to use by configuring this option.
|
| IPv4 API Endpoints |
IPv4 API endpoints are web services used to help determine the public IPv4
address of the instance running this utility. The detected IP will be used
to update the configured DNS The endpoint used is chosen at random each run. If a given endpoint cannot be accessed, other endpoints are used until an IPv4 address is provided or all endpoints have been exhausted. The default endpoints used are as follows: Users can override what endpoints to use by configuring this option.
|
| IPv6 |
Configure whether this utility will attempt to determine an IPv6 address
and attempt to configure an By default, this setting is enabled.
|
| IPv6 API Endpoint Command |
Configures a command to invoke when attempting to fetch the IPv6 address of
the instance running this utility. The returned IP will be used to update
the configured DNS Users can configure the command to use by configuring this option.
|
| IPv6 API Endpoints |
IPv6 API endpoints are web services used to help determine the public IPv6
address of the instance running this utility. The detected IP will be used
to update the configured DNS The endpoint used is chosen at random each run. If a given endpoint cannot be accessed, other endpoints are used until an IPv6 address is provided or all endpoints have been exhausted. The default endpoints used are as follows: Users can override what endpoints to use by configuring this option.
|
| Timeout |
Configures 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 (
|
| Advanced Options | |
| NFSN API Endpoint |
The 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 to
|
Docker
This 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 image
A pre-built image can be acquired using the following command:
docker pull ghcr.io/jdknight/nfsn-ddns
Prepare a configuration environment for this container by creating a
file /etc/nfsn-ddns with the contents defined in env.default
(users can use any path or filename they desire, as long as the following
docker run command 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-ddns
Self-built image
Users 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 the
docker build -t ghcr.io/jdknight/nfsn-ddns --detach -f docker/Dockerfile .
Then running the same docker run call mentioned above.
Self-managed Docker Compose
Users 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.env
Next, load up the container using docker compose:
docker compose build
docker compose up --detach
Both 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 local argument.
For example:
docker compose build --build-arg BUILD_MODE=local
docker compose up --detach
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file nfsn_ddns-0.3.0.tar.gz.
File metadata
- Download URL: nfsn_ddns-0.3.0.tar.gz
- Upload date:
- Size: 21.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 48b67f91e98bcb348ae711dfae901da742f0a429d7a4d8ef7a37880094ad1799 |
|
| MD5 | d2c5ddd1324df787befe2b071cfd6242 |
|
| BLAKE2b-256 | a05f9d25f2e810d483962b14d3b2669375891219e9f6b3292b5d5b965c5ce29c |
Provenance
The following attestation bundles were made for nfsn_ddns-0.3.0.tar.gz:
Publisher:
publish-pypi.yml on jdknight/nfsn-ddns
-
Statement type:
https://in-toto.io/Statement/v1- Predicate type:
https://docs.pypi.org/attestations/publish/v1 - Subject name:
nfsn_ddns-0.3.0.tar.gz - Subject digest:
48b67f91e98bcb348ae711dfae901da742f0a429d7a4d8ef7a37880094ad1799 - Sigstore transparency entry: 146200592
- Sigstore integration time:
- Predicate type:
File details
Details for the file nfsn_ddns-0.3.0-py3-none-any.whl.
File metadata
- Download URL: nfsn_ddns-0.3.0-py3-none-any.whl
- Upload date:
- Size: 21.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 51bb0020cc81aa4c7077faa71989ba08377aa1bf64610c66baa447ec78778faf |
|
| MD5 | 01120ea808d1c7b9c33c917e5b108bb1 |
|
| BLAKE2b-256 | 3eba2027a9bbf09bf21b69c0497a985ad3605ec19b6eed59d3d1a07c31296208 |
Provenance
The following attestation bundles were made for nfsn_ddns-0.3.0-py3-none-any.whl:
Publisher:
publish-pypi.yml on jdknight/nfsn-ddns
-
Statement type:
https://in-toto.io/Statement/v1- Predicate type:
https://docs.pypi.org/attestations/publish/v1 - Subject name:
nfsn_ddns-0.3.0-py3-none-any.whl - Subject digest:
51bb0020cc81aa4c7077faa71989ba08377aa1bf64610c66baa447ec78778faf - Sigstore transparency entry: 146200593
- Sigstore integration time:
- Predicate type:
