[help] how to write a plugin? (add public documentation request)

[atesin]

hi... i am trying to write a freedns (afraid.org) plugin for its update api v2 (https://freedns.afraid.org/dynamic/v2/)... i think i am done, but ddupdate does not list my new plugin with ddupdate -S

[leamas]

It should, for sure. Where have you installed the plugin before trying ddupdate -S?

[atesin]

short self answer: read CONTRIBUTE.md

i finished my plugin, keep in mind is very basic because i don't have the tools (i wrote it just with plain vim) and i'm not so skilled in python, neither in git... i never sent a patch request so here it goes the plugin

freedns_v2.py

"""
ddupdate plugin updating data on freedns.afraid.org api v2 random token.

See: ddupdate(8)
See: https://freedns.afraid.org
See: https://freedns.afraid.org/dynamic/v2/ (needs login)
"""

from ddupdate.ddplugin import ServicePlugin, ServiceError
from ddupdate.ddplugin import get_response

class FreednsV2Plugin(ServicePlugin):
    """
    Updates DNS data for host on freedns.afraid.org api v2.

    Freedns allows settings the IP address using an address plugin or
    just using the address as seen from the internet using the ip-disabled
    plugin. Ipv6 is supported. V2 api uses a random token which is simpler
    and more secure, your credentials are never exposed.

    Login to afraid.org and add some domain to v2 api. Take the token
    (last part of update url) and use it as 'hostname' in ddupdate.conf.
    """

    _name = 'sync.afraid.org'
    _oneliner = 'Updates on https://sync.afraid.org/'
    _url = 'https://{0}sync.afraid.org/u/{1}/'

    def register(self, log, hostname, ip, options):
        """
        Based on  https://freedns.afraid.org/dynamic/v2/, needs _url below
        to update.

        The {1} parameter is a randomized update token, generated specificly
        for each domain when enabled for api v2. The server detects source IP
        automatically, but optionally you can provide it
        """
        url = ''
        if ip and ip.v6:
            url = self._url.format('v6.', hostname) + '?address=' + str(ip.v6)
        else:
            url = self._url.format(''   , hostname)
            if ip and ip.v4:
                url += '?address=' + str(ip.v4)
        log.debug("Contacting freedns for update v2 on %s", url)
        get_response(log, url)

what it lacks:

• netrc support (i never heard of it, probably i don't need it)
• better documentation maybe
• add alternate port 8080 (not guaranteed, use it just for proxy or redirects problems)
• do something with wrong updates (send mail?, run script?, retry later?, use other method?...)
• anything i haven't thought yet... anybody feel free to improve it

[leamas]

Talking about the issue here: Have you found the Writing Plugins chapter in CONTRIBUTE.md?

Yes, you need netrc support. This is not just about netrc, it's also about how _ddupdateconfig works: it parses the netrc line and uses it to craft the user dialog. Please check examples in other plugins, there are many which just uses an API token (duckdns comes to mind). When done, please check using ddupdate-config.

The plugin documentation is perfectly fine, nothing more is required. Note that the comment in the file is displayed using --help

Submitting a new plugin this way is not common but should be ok. However, it's better done in a separate issue, this is about the documentation. As for this, the question is still if you have found CONTRIBUTE.md

[leamas]

Oops, sorry, I now see that you found CONTRIBUTE.md. It also looks like you was able to finish your work after reading it. Does this mean that we could close this issue about documentation, looking forward to a new issue with an updated plugin?

[atesin]

i looked the sources... duckdns uses 2 variables, host and token... afraid api v2 uses just 1: token, meaning that your host (domain name) is safe from curious eyes, and you can update many linked domains with just 1 token, see afraid.org documentation

and yes... the answer to "how to write and submit plugins" is not so clear... you could also mention in README.md and/or in man page ... please mention it and then close this issue yourself ;)

meanwhile i will open a new issue with my (attempt of) plugin :D

[leamas]

I'm closing this, it leads us nowhere