| Name | porkbun-ddns JSON |
| Version |
1.1.15
JSON |
| download |
| home_page | None |
| Summary | A unofficial DDNS-Client for Porkbun domains |
| upload_time | 2025-08-18 09:33:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) Nils Stein
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
porkbun
ddns
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Disclaimer
**This package is not related to or developed by Porkbun. No relationship between the developer of this package and Porkbun exists.**
**All trademarks, logos and brand names are the property of their respective owners. All company, product and service names used in this package are for identification purposes only. Use of these names,trademarks and brands does not imply endorsement.**
# Porkbun DDNS
`porkbun-ddns` is a unofficial DDNS-Client for Porkbun Domains.
This library will only update the records if the IP(s) have changed or the dns entry didn't exist before, it will also set/update A (IPv4) and AAAA (IPv6) records.
Since [porkbun-dynamic-dns-python](https://github.com/porkbundomains/porkbun-dynamic-dns-python) is deprecated I took it into my own hands to code a decent DDNS Client for Porkbun.
Inspired by [con-f-use](https://github.com/con-f-use) [pull request](https://github.com/porkbundomains/porkbun-dynamic-dns-python/pull/6), I built a pip Package and a docker container.
As alternative to cert-bun use my [lego-certbot](https://github.com/mietzen/lego-certbot) image.
## Setup on Porkbun
Make sure that any domain you use this client with has API access enabled. See the below picture for reference.
If this is not enabled, you'll see an error about your API keys being invalid, despite them being correct.
# CLI
**Minimum required python version: 3.10**
## Install via pip
```shell
pip install porkbun-ddns
```
## Usage
```Shell
usage: porkbun-ddns [-h] [-c CONFIG] [-e ENDPOINT] [-pk APIKEY] [-sk SECRETAPIKEY] [-i [PUBLIC_IPS ...]] [-f FRITZBOX] [-4 | -6] [-v] [--env_only] domain [subdomains ...]
positional arguments:
domain Domain to be updated
subdomains Subdomain(s)
options:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
Path to config file (default: ~/.config/porkbun-ddns-config.json)
-e ENDPOINT, --endpoint ENDPOINT
The endpoint
-pk APIKEY, --apikey APIKEY
The Porkbun-API-key
-sk SECRETAPIKEY, --secretapikey SECRETAPIKEY
The secret API-key
-i [PUBLIC_IPS ...], --public-ips [PUBLIC_IPS ...]
Public IPs (v4 and or v6)
-f FRITZBOX, --fritzbox FRITZBOX
IP or Domain of your Fritz!Box
-4, --ipv4-only Only set/update IPv4 A Records
-6, --ipv6-only Only set/update IPv6 AAAA Records
-v, --verbose Show Debug Output
--env_only Don't use any config, get all variables from the environment
```
### The parameter *endpoint*, *apikey*, *secretapikey*
These parameter are required for each run of the program. The program will take the values for these (in this order) from:
1. The command-line-arguments (`-pk pk1_xxx`)
2. The environment-variables (`export PORKBUN_APIKEY='pk1_xxx'`)
3. The config-file (`apikey="pk_xxx"`)
So if a value is set through the CLI and in the file, the CLI-value will be used. This allows for a default-configuration in the config-file, whose settings can be selectively overridden through enviromnment-variables or CLI-arguments.
### Examples
```shell
# using the default config-file in ~/.config/porkbun-ddns-config.json:
$ porkbun-ddns domain.com my_subdomain
# Using only environment variables:
# PORKBUN_APIKEY
# PORKBUN_SECRETAPIKEY
# PORKBUN_ENDPOINT (Optional)
$ porkbun-ddns domain.com my_subdomain --env_only
# Specific config-file:
$ porkbun-ddns domain.com my_subdomain -c "./config.json"
# Multiple subdomains:
$ porkbun-ddns domain.com my_subdomain_1 my_subdomain_2 my_subdomain_3
# Set root and subdomains:
$ porkbun-ddns domain.com @ my_subdomain_1 my_subdomain_2 my_subdomain_3
# Set wildcard domain:
$ porkbun-ddns domain.com '*'
# Set IP's explicit
$ porkbun-ddns domain.com my_subdomain -i '1.2.3.4' '1234:abcd:0:4567::8900'
# Use Fritz!Box to obtain IP's and set IPv4 A Record only
$ porkbun-ddns "./config.json" domain.com my_subdomain -f fritz.box -4
```
You can set up a cron job get the full path to porkbun-ddns with `which porkbun-ddns`, then execute `crontab -e` and add the following line:
```
*/30 * * * * <PORKBUN-DDNS-PATH>/porkbun-ddns "<YOUR-PATH>/config.json" domain.com my.subdomain >/dev/null 2>&1
```
`config.json` example:
```
{
"endpoint":"https://api.porkbun.com/api/json/v3",
"apikey": "pk1_xxx",
"secretapikey": "sk1_xxx"
}
```
# Docker compose
```yaml
services:
porkbun-ddns:
image: "mietzen/porkbun-ddns:latest"
container_name: porkbun-ddns
environment:
DOMAIN: "domain.com" # Your Porkbun domain
SUBDOMAINS: "my_subdomain,my_other_subdomain,my_subsubdomain.my_subdomain" # Subdomains comma spreaded
SECRETAPIKEY: "<YOUR-SECRETAPIKEY>" # Your Porkbun Secret-API-Key
APIKEY: "<YOUR-APIKEY>" # Your Porkbun API-Key
# PUBLIC_IPS: "1.2.3.4,2001:043e::1" # Set if you got static IP's
# FRITZBOX: "192.168.178.1" # Use Fritz!BOX to obtain Public IP's
# SLEEP: "300" # Seconds to sleep between DynDNS runs
# IPV4: "TRUE" # Set IPv4 address
# IPV6: "TRUE" # Set IPv6 address
# DEBUG: "FALSE" # DEBUG LOGGING
restart: unless-stopped
# # Uncomment below to let it detect ipv6 address:
# networks:
# - ipv6_enabled
# networks:
# ipv6_enabled:
# enable_ipv6: true
```
# Docker run
```shell
docker run -d \
-e DOMAIN="domain.com" \
-e SUBDOMAINS="my_subdomain,my_other_subdomain,my_subsubdomain.my_subdomain" \
-e SECRETAPIKEY="<YOUR-SECRETAPIKEY>" \
-e APIKEY="<YOUR-APIKEY>" \
--name porkbun-ddns \
--restart unless-stopped \
mietzen/porkbun-ddns:latest
```
# Python
**Minimum required python version: 3.10**
```python
from pathlib import Path
from porkbun_ddns import PorkbunDDNS
from porkbun_ddns.config import Config, DEFAULT_ENDPOINT, extract_config
config = Config(DEFAULT_ENDPOINT, "YOUR-APIKEY", "YOUR-SECRETAPIKEY")
porkbun_ddns = PorkbunDDNS(config, 'domain.com')
# config = extract_config(Path("./config.json"))
# porkbun_ddns = PorkbunDDNS(config, 'domain.com')
# porkbun_ddns_ip = PorkbunDDNS(config, 'domain.com', public_ips=['1.2.3.4','1234:abcd:0:4567::8900'])
# porkbun_ddns_fritz = PorkbunDDNS(config, 'domain.com', fritzbox_ip='fritz.box', ipv6=False)
porkbun_ddns.set_subdomain('my_subdomain')
porkbun_ddns.update_records()
```
Raw data
{
"_id": null,
"home_page": null,
"name": "porkbun-ddns",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "porkbun, ddns",
"author": null,
"author_email": "Nils Stein <github.nstein@mailbox.org>",
"download_url": null,
"platform": null,
"description": "# Disclaimer\n\n**This package is not related to or developed by Porkbun. No relationship between the developer of this package and Porkbun exists.**\n\n**All trademarks, logos and brand names are the property of their respective owners. All company, product and service names used in this package are for identification purposes only. Use of these names,trademarks and brands does not imply endorsement.**\n\n# Porkbun DDNS\n\n`porkbun-ddns` is a unofficial DDNS-Client for Porkbun Domains.\nThis library will only update the records if the IP(s) have changed or the dns entry didn't exist before, it will also set/update A (IPv4) and AAAA (IPv6) records.\n\n\nSince [porkbun-dynamic-dns-python](https://github.com/porkbundomains/porkbun-dynamic-dns-python) is deprecated I took it into my own hands to code a decent DDNS Client for Porkbun.\nInspired by [con-f-use](https://github.com/con-f-use) [pull request](https://github.com/porkbundomains/porkbun-dynamic-dns-python/pull/6), I built a pip Package and a docker container.\n\nAs alternative to cert-bun use my [lego-certbot](https://github.com/mietzen/lego-certbot) image.\n\n## Setup on Porkbun\n\nMake sure that any domain you use this client with has API access enabled. See the below picture for reference.\n\n\n\nIf this is not enabled, you'll see an error about your API keys being invalid, despite them being correct.\n\n# CLI\n\n**Minimum required python version: 3.10**\n\n## Install via pip\n\n```shell\npip install porkbun-ddns\n```\n\n## Usage\n\n```Shell\nusage: porkbun-ddns [-h] [-c CONFIG] [-e ENDPOINT] [-pk APIKEY] [-sk SECRETAPIKEY] [-i [PUBLIC_IPS ...]] [-f FRITZBOX] [-4 | -6] [-v] [--env_only] domain [subdomains ...]\n\npositional arguments:\n domain Domain to be updated\n subdomains Subdomain(s)\n\noptions:\n -h, --help show this help message and exit\n -c CONFIG, --config CONFIG\n Path to config file (default: ~/.config/porkbun-ddns-config.json)\n -e ENDPOINT, --endpoint ENDPOINT\n The endpoint\n -pk APIKEY, --apikey APIKEY\n The Porkbun-API-key\n -sk SECRETAPIKEY, --secretapikey SECRETAPIKEY\n The secret API-key\n -i [PUBLIC_IPS ...], --public-ips [PUBLIC_IPS ...]\n Public IPs (v4 and or v6)\n -f FRITZBOX, --fritzbox FRITZBOX\n IP or Domain of your Fritz!Box\n -4, --ipv4-only Only set/update IPv4 A Records\n -6, --ipv6-only Only set/update IPv6 AAAA Records\n -v, --verbose Show Debug Output\n --env_only Don't use any config, get all variables from the environment\n```\n\n### The parameter *endpoint*, *apikey*, *secretapikey*\n\nThese parameter are required for each run of the program. The program will take the values for these (in this order) from:\n\n1. The command-line-arguments (`-pk pk1_xxx`)\n2. The environment-variables (`export PORKBUN_APIKEY='pk1_xxx'`)\n3. The config-file (`apikey=\"pk_xxx\"`)\n\nSo if a value is set through the CLI and in the file, the CLI-value will be used. This allows for a default-configuration in the config-file, whose settings can be selectively overridden through enviromnment-variables or CLI-arguments.\n\n### Examples\n\n```shell\n# using the default config-file in ~/.config/porkbun-ddns-config.json:\n$ porkbun-ddns domain.com my_subdomain\n\n# Using only environment variables:\n# PORKBUN_APIKEY\n# PORKBUN_SECRETAPIKEY\n# PORKBUN_ENDPOINT (Optional)\n$ porkbun-ddns domain.com my_subdomain --env_only\n\n# Specific config-file:\n$ porkbun-ddns domain.com my_subdomain -c \"./config.json\"\n\n# Multiple subdomains:\n$ porkbun-ddns domain.com my_subdomain_1 my_subdomain_2 my_subdomain_3\n\n# Set root and subdomains:\n$ porkbun-ddns domain.com @ my_subdomain_1 my_subdomain_2 my_subdomain_3\n\n# Set wildcard domain:\n$ porkbun-ddns domain.com '*'\n\n# Set IP's explicit\n$ porkbun-ddns domain.com my_subdomain -i '1.2.3.4' '1234:abcd:0:4567::8900'\n\n# Use Fritz!Box to obtain IP's and set IPv4 A Record only\n$ porkbun-ddns \"./config.json\" domain.com my_subdomain -f fritz.box -4\n```\n\nYou can set up a cron job get the full path to porkbun-ddns with `which porkbun-ddns`, then execute `crontab -e` and add the following line:\n\n```\n*/30 * * * * <PORKBUN-DDNS-PATH>/porkbun-ddns \"<YOUR-PATH>/config.json\" domain.com my.subdomain >/dev/null 2>&1\n```\n\n`config.json` example:\n\n```\n{\n \"endpoint\":\"https://api.porkbun.com/api/json/v3\",\n \"apikey\": \"pk1_xxx\",\n \"secretapikey\": \"sk1_xxx\"\n}\n```\n\n# Docker compose\n\n```yaml\nservices:\n porkbun-ddns:\n image: \"mietzen/porkbun-ddns:latest\"\n container_name: porkbun-ddns\n environment:\n DOMAIN: \"domain.com\" # Your Porkbun domain\n SUBDOMAINS: \"my_subdomain,my_other_subdomain,my_subsubdomain.my_subdomain\" # Subdomains comma spreaded\n SECRETAPIKEY: \"<YOUR-SECRETAPIKEY>\" # Your Porkbun Secret-API-Key\n APIKEY: \"<YOUR-APIKEY>\" # Your Porkbun API-Key\n # PUBLIC_IPS: \"1.2.3.4,2001:043e::1\" # Set if you got static IP's\n # FRITZBOX: \"192.168.178.1\" # Use Fritz!BOX to obtain Public IP's\n # SLEEP: \"300\" # Seconds to sleep between DynDNS runs\n # IPV4: \"TRUE\" # Set IPv4 address\n # IPV6: \"TRUE\" # Set IPv6 address\n # DEBUG: \"FALSE\" # DEBUG LOGGING\n restart: unless-stopped\n\n# # Uncomment below to let it detect ipv6 address:\n# networks:\n# - ipv6_enabled\n\n# networks:\n# ipv6_enabled:\n# enable_ipv6: true\n\n```\n\n# Docker run\n\n```shell\ndocker run -d \\\n -e DOMAIN=\"domain.com\" \\\n -e SUBDOMAINS=\"my_subdomain,my_other_subdomain,my_subsubdomain.my_subdomain\" \\\n -e SECRETAPIKEY=\"<YOUR-SECRETAPIKEY>\" \\\n -e APIKEY=\"<YOUR-APIKEY>\" \\\n --name porkbun-ddns \\\n --restart unless-stopped \\\n mietzen/porkbun-ddns:latest\n```\n\n# Python\n\n**Minimum required python version: 3.10**\n\n```python\nfrom pathlib import Path\nfrom porkbun_ddns import PorkbunDDNS\nfrom porkbun_ddns.config import Config, DEFAULT_ENDPOINT, extract_config\n\n\nconfig = Config(DEFAULT_ENDPOINT, \"YOUR-APIKEY\", \"YOUR-SECRETAPIKEY\")\nporkbun_ddns = PorkbunDDNS(config, 'domain.com')\n# config = extract_config(Path(\"./config.json\"))\n# porkbun_ddns = PorkbunDDNS(config, 'domain.com')\n# porkbun_ddns_ip = PorkbunDDNS(config, 'domain.com', public_ips=['1.2.3.4','1234:abcd:0:4567::8900'])\n# porkbun_ddns_fritz = PorkbunDDNS(config, 'domain.com', fritzbox_ip='fritz.box', ipv6=False)\n\nporkbun_ddns.set_subdomain('my_subdomain')\nporkbun_ddns.update_records()\n```\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) Nils Stein\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A unofficial DDNS-Client for Porkbun domains",
"version": "1.1.15",
"project_urls": {
"repository": "https://github.com/mietzen/porkbun-ddns"
},
"split_keywords": [
"porkbun",
" ddns"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c7dbf16005a88a7c6bc7e284b69d4da9f44edb380d062cea24c5b80edaf7d782",
"md5": "07c41bec8ebdb8f4e0252ce7ae4968b1",
"sha256": "feb7e137fa6ed03fd511933ca30f36342543bd9ce81130afb9c59ee17f93ac72"
},
"downloads": -1,
"filename": "porkbun_ddns-1.1.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "07c41bec8ebdb8f4e0252ce7ae4968b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11825,
"upload_time": "2025-08-18T09:33:33",
"upload_time_iso_8601": "2025-08-18T09:33:33.805536Z",
"url": "https://files.pythonhosted.org/packages/c7/db/f16005a88a7c6bc7e284b69d4da9f44edb380d062cea24c5b80edaf7d782/porkbun_ddns-1.1.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 09:33:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mietzen",
"github_project": "porkbun-ddns",
"github_fetch_exception": true,
"lcname": "porkbun-ddns"
}
