{"id":14037253,"url":"https://github.com/mkorthof/freenom-script","last_synced_at":"2025-09-27T15:31:59.551Z","repository":{"id":43641628,"uuid":"170899883","full_name":"mkorthof/freenom-script","owner":"mkorthof","description":"Freenom.com Domain Renewal and Dynamic DNS script","archived":true,"fork":false,"pushed_at":"2023-12-04T04:09:01.000Z","size":404,"stargazers_count":343,"open_issues_count":4,"forks_count":84,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-01-11T18:42:50.131Z","etag":null,"topics":["bash","bash-script","domain","dyndns","freenom"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkorthof.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-02-15T17:04:30.000Z","updated_at":"2025-01-08T10:54:13.000Z","dependencies_parsed_at":"2023-12-04T05:22:29.566Z","dependency_job_id":"ae6f1868-850d-4145-a5d5-92d8beae5979","html_url":"https://github.com/mkorthof/freenom-script","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkorthof%2Ffreenom-script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkorthof%2Ffreenom-script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkorthof%2Ffreenom-script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkorthof%2Ffreenom-script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkorthof","download_url":"https://codeload.github.com/mkorthof/freenom-script/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234448346,"owners_count":18834213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-script","domain","dyndns","freenom"],"created_at":"2024-08-12T03:02:37.140Z","updated_at":"2025-09-27T15:31:59.230Z","avatar_url":"https://github.com/mkorthof.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# Domain Renewal and DynDNS for Freenom.com\n\n[![Shellcheck](https://github.com/mkorthof/freenom-script/actions/workflows/shellcheck.yml/badge.svg)](https://github.com/mkorthof/freenom-script/actions/workflows/shellcheck.yml)\n[![Docker](https://github.com/mkorthof/freenom-script/actions/workflows/docker.yml/badge.svg)](https://github.com/mkorthof/freenom-script/actions/workflows/docker.yml)\n[![BATS](https://github.com/mkorthof/freenom-script/actions/workflows/bats.yml/badge.svg)](https://github.com/mkorthof/freenom-script/actions/workflows/bats.yml)\n\n## Last Update ##\n\n⚠ As it seems Freenom is no longer able to manage any of their ccTLDs .tk .cf .ga etc and lost their ICANN accreditation for gTLDs, this really is the end  (December 2023).\n\n⚠ Freenom recently added CAPTCHA from AWS WAF, causing this script to stop working (June 2023).\n\n***Latest version: v2023-08-03 ([CHANGES.md](CHANGES.md))***\n\n**Make sure to add new config options when updating script**\n\n---\n\nThis shell script makes sure your Freenom domains don't expire by auto renewing them. It can also set a DNS record with the clients ip address.\n\nYou'll need to have already registered an account at Freenom.com with at least one (free) domain added, before you can run the script.\n\n## Usage\n\n```shell\n\nfreenom.com Domain Renewal and DynDNS\n-------------------------------------\n\nUsage:      freenom.sh -l [-d]\n            freenom.sh -r \u003cdomain OR -a\u003e [-s \u003csubdomain\u003e]\n            freenom.sh -u \u003cdomain\u003e [-s \u003csubdomain\u003e] [-m \u003cip\u003e] [-f]\n            freenom.sh -z \u003cdomain\u003e\n\nOptions:    -l    List all domains and id's in account\n                  add [-d] to show renewal Details\n            -r    Renew \u003cdomain\u003e or use '-r -a' to update All\n                  add [-s] to renew \u003cSubdomain\u003e\n            -u    Update \u003cdomain\u003e A record with current ip\n                  add [-s] to update \u003cSubdomain\u003e record\n                  add [-m \u003cip\u003e] to Manually update static \u003cip\u003e\n                  add [-f] to Force update on unchanged ip\n            -z    Zone for \u003cdomain\u003e, shows dns records\n\n            -4    Use ipv4 and modify A record on \"-u\" (default)\n            -6    Use ipv6 and modify AAAA record on \"-u\"\n            -c    Config \u003cfile\u003e to use, instead of freenom.conf\n            -i    Ip commands list, used to get current ip\n            -o    Output renewals, shows html file(s)\n\nExamples    ./freenom.sh -r example.com\n            ./freenom.sh -c /etc/mycustom.conf -r -a\n            ./freenom.sh -u example.com -s mail\n\n            * When \"-u\" or \"-r\" is used with argument \u003cdomain\u003e\n              any settings in script or config file are overridden\n\n```\n\n## Installation\n\nUsing a full Linux distro including coreutils is recommended (e.g. Debian). Embedded and BusyBox based systems are untested and will probably not work correctly or at all.\n\n_Note that this shell script requires recent versions of \"Bash\" and \"cURL\"_\n\n### Auto Installer\n\nRun: `make install` \n\n(from git clone directory)\n\nThis automatically installs the script, .conf file and configures scheduler.\n\n### Manual install\n\nSuggested installation path: \"/usr/local/bin/freenom.sh\"\n\nAnd for the config file: \"/usr/local/etc/freenom.conf\"\n\n### Docker\n\nThere's an [image](https://github.com/mkorthof/freenom-script/pkgs/container/freenom_script) available from GitHub Container Registry which you can run like this:\n\n `docker run --rm --env freenom_email=\"you@example.com\" --env freenom_passwd=\"yourpassword\" ghcr.io/mkorthof/freenom_script -l`\n\nFor more information see [Docker.md](docs/Docker.md)\n\n## Configuration\n\nSettings can be changed in the script itself or set in a separate config file (default). Every setting has comments with possible options and examples.\n\nFirst edit config and **set your email and password** which you use to sign-in to freenom.com\n\n- The default filename is \"freenom.conf\" in the same location as the script, or \"/usr/local/etc/freenom.conf\"\n- You can also use `freenom.sh -c /path/to/file.conf`\n- To optionally put config in the script itself instead: copy settings from conf file into `freenom.sh` (before \"Main\")\n\nDefault settings such as retries and timeouts can be changed, they are however OK to leave as-is (see [Overrides.md](docs/Overrides.md)).\n\n### Testing\n\nTest the script by running `freenom.sh -l` and make sure your domains are listed. To Renew domains or Update A record, see [Usage](#usage) or `freenom.sh -h`  \n\n## Scheduling\n\nOptionally you can schedule the script to run automatically. The installer creates \"/etc/cron.d/freenom\" or systemd timers in 'system mode' so the script runs at certain intervals. It will output a message with instructions on how to set your domain(s) to renew/update or renew all:\n\n- Cron:\n    - edit the created file in /etc/cron.d and uncomment line(s)\n- Systemd:\n    - `systemctl enable --now freenom-renew-all.timer`\n    - `systemctl enable --now freenom-update@example.tk.timer`\n    - `systemctl enable --now freenom-update@mysubdom.example.tk.timer`\n    \n_If systemd is not available on your system, the installer will use cron instead._\n\n### Manual setup\n\nSee [Scheduling.md](docs/Scheduling.md)\n\n## Notifications\n\n### Email\n\nTo enable email alerts, make sure `MTA` is set; the default is `/usr/sbin/sendmail`. Emails will be sent on renewal or update errors. If you do not have/want an MTA installed you could use [bashmail](https://git.io/JJdto) instead.\n\nIf you want to receive the alerts on a different email address than `freenom_email` set `RCPTTO`. You can also set an optional \"From\" address: `MAILFROM=\"Freenom Script \u003cfreenom-script@example.tk\u003e\"`\n\nLeaving `MTA` empty or commented disables alerts.\n\n### Apprise\n\nUses external lib to send notification to many services like Telegram, Discord, Slack, Amazon SNS, MS Teams etc.\n\nTo enable [Apprise](https://github.com/caronc/apprise) notifications, make sure `APPRISE` is set to the location where you installed the Apprise CLI; the default is `/usr/local/bin/apprise`. You must also set the `APPRISE_SERVER_URLS` array to contain one or more server URLs. Notifications are sent to all of the listed server URLs. As with email notifications, Apprise notifications are sent on renewal or update errors.\n\nFor details on how to construct server URLs, refer to [supported notifications](https://github.com/caronc/apprise#supported-notifications).\n\nLeaving the `APPRISE_SERVER_URLS` array empty disables Apprise notifications. \n\n## DynDNS\n\nTo update A or AAAA records the nameservers for the domain must be set to the default Freenom Name Servers.\n\nThe record will be added if there is none, or modified if the record already exists. Your current ip address will be used as value (aka \"Target\").\n\n### IP Address\n\nThe script uses 3 methods to get your current ip address from a number of public services:\n\n- HTTP method: `curl https://checkip.amazonaws.com`\n- DNS method: `dig TXT +short o-o.myaddr.l.google.com @ns1.google.com`\n- Manually: you can also set a static ip address instead of auto detect (see below)\n\nThere are a few more HTTP and DNS services defined for redundancy, the script will choose one at random. By default it will retry to get the ip 3 times.\n\nOnce your ip is found it's written to \"freenom_\\\u003cdomain\\\u003e.ip4\" (or 'ip6'). Same if freenom returns dnserror \"There were no changes\". This is to prevent unnecessary updates in case the ip is unchanged.\nTo force an update you can remove this file which is located in the default output path: \"/var/log\".\n\nTo manually update: set `freenom_static_ip=\u003cyour ip\u003e` and `freenom_update_manual=\"1\"`, or use the `-m` option.\n\n### Issues\n\n#### Timeout\n\nIn case of dns issues where resolving does not work correctly and curl times out to https://my.freecom.com ('exit code 28'), try setting `freenom_http_resolve=\"1\"`. This make sure curl uses Freenoms own public dns servers.\n\n#### Account\n\nYou need an actual Freenom account, as using Social Sign-in will not work. Workaround: use password reset, see [KB](https://my.freenom.com/knowledgebase.php?action=displayarticle\u0026id=27) and issue [#56](https://github.com/mkorthof/freenom-script/issues/56).\n\n#### Get ip\n\nMake sure 'curl' and/or 'dig' is installed (e.g. debian: dnsutils or redhat: bind-utils). In case of issues try running curl and dig command manually.\n\n- To list all 'get ip' commands run `freenom.sh -i` (or `grep getIp freenom.conf`)\n- To disable IPv6: set `freenom_update_ipv=\"4\"`\n- To disable dig: set `freenom_update_dig=\"0\"`\n\n## Files\n\n- Installer: Makefile (`make install`)\n- Script/config: `freenom.sh` and `freenom.conf`\n- Output:\n  - Path: `\"/var/log/freenom/\"` (default)\n  - Files: `freenom.log`, `freenom_\u003cdomain\u003e.ip{4,6}`, `freenom_renewalResult-\u003cid\u003e.html`\n- View Results: use `freenom.sh -o` to view html files\n  \nAlso see comment \"Output files\" and `freenom_out_dir` variable in conf.\n\n### Updating\n\nUsually you can just replace \"freenom.sh\" with the new version, if you're using a separate config file.\n\nAn exception is when config options were added/changed which you may need to compare and merge. Such config changes are listed in [CHANGES.md](CHANGES.md).\n\n### Uninstall\n\nRun `make uninstall`.\n\nYou can also manually reverse the steps under [Installation](#installation) above (e.g. remove .sh, .conf and scheduler files).\n\n## Sources\n\nSee included [orig](orig) dir\n\n- Original script: [gist.github.com/a-c-t-i-n-i-u-m/bc4b1ff265b277dbf195](https://gist.github.com/a-c-t-i-n-i-u-m/bc4b1ff265b277dbf195)\n- Updated script: [gist.github.com/pgaulon/3a844a626458f56903d88c5bb1463cc6](https://gist.github.com/pgaulon/3a844a626458f56903d88c5bb1463cc6)\n- Reference: [github.com/dabendan2/freenom-dns](https://github.com/dabendan2/freenom-dns) (nodejs/npm)\n- Reference: [github.com/patrikx3/freenom](https://github.com/patrikx3/freenom) (nodejs/npm)\n\n## Changes\n\nSee [CHANGES.md](CHANGES.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkorthof%2Ffreenom-script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkorthof%2Ffreenom-script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkorthof%2Ffreenom-script/lists"}