Skip to content
Domain Renewal and Dynamic DNS support shell script for
HTML Shell Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Domain Renewal and DynDNS for

Latest version: v2019-11-17 (Changes)

NOTE: Make sure to add new config options when updating script

This shell script makes sure your Freenom domains don't expire by auto renewing them. It's original functionality of updating an A record with the clients ip address is also retained.

You'll need to have already registered an account at with at least one (free) domain added before you can run the script.


Note that this shell script requires a recent version of "Bash"


Run make install from git clone directory to automatically install the script, conf file and to configure scheduler.


  1. Suggested installation path: "/usr/local/bin" and "/usr/local/etc" for the config file
  2. Edit config and set your email and password which you use to sign-in to


Test the script by running -l and make sure your domains are listed. To update A record or Renew domains, see Usage below or -h


Settings can be changed in the script itself or set in a seperate config file (default). Every setting has comments with possible options and examples.

  • The default filename is "freenom.conf" in the same location as the script or "/usr/local/etc/freenom.conf"
  • You can also use -c /path/to/file.conf
  • To optionally put config in the script itself instead: copy settings from conf into (before "Main")


The installer creates "/etc/cron.d/freenom" or systemd timers so the script runs automatically at certain intervals. You just have to set your domain(s), the installer will tell you how. You can also have a look at the Examples and manual steps below.


To manually configure cron:

  • Copy script and conf files (see Installation)
  • Copy cron.d/freenom to "/etc/cron.d/freenom" and edit it, or create the file yourself with these line(s)


0 9 * * 0 root bash -c 'sleep $((RANDOM \% 60))m; /usr/local/bin/ -r -a'
0 * * * * root bash -c 'sleep $((RANDOM \% 15))m; /usr/local/bin/ -u'

This first line in this example will run the script with "renew all domains" options every week on Sunday between 9.00 and 10.00

The second line updates the A record of with the current client ip address, at hourly intervals


Alternatively the same can be accomplished by manually adding a systemd.timer

Thanks to @sdcloudt you can use the templates from the systemd dir.

Copy the files to e.g. /etc/systemd/user or ~/.config/systemd/user. Then reload systemd and either manually add symlinks or enable the unit to create a service instance for your domain.


# manually:
mkdir /etc/systemd/user/
ln -s /etc/systemd/user/freenom-renew@.service /etc/systemd/user/
# or, renew all domains:
ln -s /etc/systemd/user/freenom-renew-all@.service /etc/systemd/user/
ln -s /etc/systemd/user/freenom-update@.service /etc/systemd/user/
# always reload systemd first:
systemctl daemon-reload
# this will create symlinks automatically:
systemd enable --now
# or, renew all domains:
systemd enable --now freenom-renew-all@.service
systemd enable --now

Optional Overrides

The following options can be changed in config, they are however OK to leave as-is.

freenom_http_retry="3"        # number of curl retries
freenom_update_force="0"      # [0/1] force ip update, even if unchanged
freenom_update_ttl="3600"     # ttl in sec (changed from 14440 to 3600)
freenom_update_ip_retry="3"   # number of retries to get ip
freenom_update_ip_log="1"     # [0/1] log 'skipped same ip' msg
freenom_renew_log="1"         # [0/1] log renew warnings details
freenom_list_bind="0"         # [0/1] output isc bind zone format


freenom_update_ip="0"         # [0/1] arg "-u"
freenom_update_manual="0"     # [0/1] arg "-m"
freenom_update_all="0"        # [0/1] arg "-a" (future update, not working yet)
freenom_list="0"              # [0/1] arg "-l"
freenom_list_renewals="0"     # [0/1] args "-l -d"
freenom_list_records="0"      # [0/1] arg "-z"
freenom_renew_domain="0"      # [0/1] arg "-r"
freenom_renew_all="0"         # [0/1] args "-r -a"


To update A or AAAA records the nameservers for the domain must be set to the default Freenom Name Server.

  • As value your current ip address will be used ("Target")
  • An record will be added if there is none or modified if the record already exists

IP Address

To get your current ip address from a number of public services the script uses 2 methods, HTTP and DNS:

  • HTTP method: curl
  • DNS method: dig TXT +short
  • Or, manually: updates static ip address instead of auto detect

There are a few more services defined for redundancy, the script will choose one at random. By default it will retry 3 times to get ip.

Once your ip is found it's written to "freenom.ip4.domain.lock" (or ip6) to prevent unnecessary updates in case the ip is unchanged. To force an update you can remove this file which is located in the default output path "/var/log".

To manually update using set freenom_static_ip and freenom_update_manual="0" or use "-m" option.


In case of issues try running the curl and dig command above manually.

  • To list all services check the getIp array e.g. run grep getIp
  • To disable IPv6: set freenom_update_ipv="4"
  • To disable dig: set freenom_update_dig="0"

Used Files

  • Installer:
    • Makefile
  • Script:
    • freenom.conf
  • Output:
    • Default path: "/var/log/freenom/"
    • freenom.log
    • freenom_<domain>.ip{4,6}
    • freenom_renewalResult-<id>.html
  • More info:
    • See "Output files" and "freenom_out_dir" variable in config
    • Use -o to view Result html files



   -l [-d]
   -r <domain> [-s <subdomain>] | [-a]
   -u <domain> [-s <subdomain>] [-m <ip>] [-f]
   -z <domain>

            -l    List all domains with id's in account
                  add [-d] to show renewal Details
            -r    Renew domain(s)
                  add [-a] to renew All domains
            -u    Update <domain> A record with current ip
                  add [-s] to update <Subdomain>
                  add [-m <ip>] to manually update static <ip>
                  add [-f] to force update on unchanged ip
            -z    Zone listing of dns records for <domain>

            -4    Use ipv4 and modify A record on "-u" (default)
            -6    Use ipv6 and modify AAAA record on "-u"
            -c    Config <file> to be used instead freenom.conf
            -i    Ip commands list used to get current ip
            -o    Output html result file(s) for renewals

            ./ -r
            ./ -c /etc/myfn.conf -r -a
            ./ -u -s mail

            Using "-u" or "-r" and specifying <domain> as argument
            will override any settings in script or config file


Usually you can just replace "" with the new version (unless you're not using a seperate config file).

An exeption is when config options were added/changed which you may need to compare and merge. Such config changes are listed below.


Run make uninstall.

You can also manually reverse the steps under Installation above (remove .sh, .conf and scheduler files).



  • [20190000] added referer url to curl to fix login
  • [20190000] fixed token
  • [20190000] made updating ip optional
  • [20190000] added domain renewals
  • [20190000] added logging
  • [20190317] handling of existing dns records (ip update)
  • [20190317] retry getting current ip
  • [20190420] option to use seperate .conf file
  • [20190420] option to list existing dns records
  • [20190420] option to skip renewal notice details in log
  • [20190621] added tests (BATS)
  • [20190621] changed 'cannot renew until' warnings to notices
  • [20190621] added recType check (A or AAAA) for dyndns
  • [20190920] changed out dir, config change: freenom_out_dir="/var/log/freenom"
  • [20190920] added curl retries, config change: freenom_http_retry="3"
  • [20190922] fixed issue #12 (sdcloudt)
  • [20190931] added systemd templates (PR #15 from sdcloudt)
  • [20190927] added installer
  • [20191005] errorUpdateResult is no longer saved to html file
  • [20191017] changed default conf path to /usr/local/etc
  • [20191108] static ip update (#18), config change:
    • freenom_static_ip=""
    • freenom_update_manual="0"
  • [20191125] update all domains (#19), config change only: (not working yet)
    • freenom_update_all="0"

More details: git log --pretty=short --name-only

You can’t perform that action at this time.