Merge pull request #6 from domdomegg/docs-tidy-up

docs: Significant tidy-up and simplification, add porkbun protocol

general.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: "Configuration: General"
+nav_order: 2
+---
+
+# Introduction
+
+This page describes general configuration options for ddclient. This is one of the three pieces of ddclient configuration alongside routers and protocols. Start on the [homepage](./index.md) for a breakdown of how these interact.
+
+Most users are unlikely to need to specify many of these options.
+
+# Reference
+
+option              | result
+--------------------|-------
+-daemon delay       | run as a daemon, every `delay` number of seconds (default: 0).
+-{no}foreground     | do not fork (default: noforeground) (since r113)
+-proxy host         | use 'host' as the HTTP proxy.
+-server host        | update DNS information on 'host' (default: members.dyndns.org).
+-protocol type      | update protocol used (default: dyndns2).
+-file path          | load configuration information from 'path'. Only works when given as a command line argument. (default: /etc/ddclient/ddclient.conf).
+-cache path         | record address used in 'path' (default: /etc/ddclient/ddclient.cache).
+-pid path           | record process id in 'path'.
+-use which          | how the should IP address be obtained. (default: ip). More information about the possible use-arguments can be found on the supported routers page
+-ip address         | set the IP address to 'address'. 
+-postscript script  | run 'script' after updating. The new IP address is added as argument.
+-if interface       | obtain IP address from 'interface' (default: ppp0).
+-if-skip pattern    | skip any IP addresses before 'pattern' in the output of ifconfig {if}.
+-web provider|url | obtain IP address from provider's IP checking page (default: dyndns).
+-web-skip pattern | skip any IP addresses before 'pattern' on the web provider|url.
+-fw address|url | obtain IP address from firewall at 'address'.
+-fw-skip pattern | skip any IP addresses before 'pattern' on the firewall address|url. 
+-fw-login login | use 'login' when getting IP from fw. 
+-fw-password secret | use password 'secret' when getting IP from fw. 
+-cmd program | obtain IP address from by calling {program}. 
+-cmd-skip pattern | skip any IP addresses before 'pattern' in the output of {cmd}. 
+-login user | login as 'user'. 
+-password secret | use password 'secret'. 
+-host host | update DNS information for 'host'. 
+-{no}ssl   | do updates over encrypted SSL connection (default: nossl).  Works only on a few providers.
+-{no}retry | retry failed updates. (default: noretry).
+-{no}force | force an update even if the update may be unnecessary (default: noforce).
+-timeout max | wait at most 'max' seconds for the host to respond (default: 0).
+-{no}syslog | log messages to syslog (default: nosyslog).
+-facility {type} | log messages to syslog to facility {type} (default: daemon).
+-priority {pri} | log messages to syslog with priority {pri} (default: notice).
+-mail address | e-mail messages to {address}.
+-mail-failure address | e-mail messages for failed updates to {address}.
+-{no}exec | do {not} execute; just show what would be done (default: exec).
+-{no}debug | print {no} debugging information (default: nodebug).
+-{no}verbose | print {no} verbose information (default: noverbose).
+-{no}quiet | print {no} messages for unnecessary updates (default: noquiet).
+-help | print a help message (default: nohelp).
+-{no}query | print {no} ip addresses and exit.

index.md

@@ -1,101 +1,80 @@
 ---
 layout: default
-title: Home page
+title: Home
 nav_order: 1
 ---
 
-<!-- 
-
-Ddclient is a Perl client used to update dynamic DNS entries for accounts on 'Dynamic DNS Network Services' free DNS service. It currently supports a lot of different routers and a few different services.
-
-[[project_screenshots]]
-[[project_admins]]
-[[download_button]]
-
-Other instuctions on how to use the wiki syntax can be found on https://sourceforge.net/p/necessitas/wiki/markdown_syntax/ 
-
-Project for rent
-Unfortunatly I (wimpunk) don't have any spare time to work on this project.  If there's anyone out there willing to help me and eventually tak over this project, pleas let it know at [the mailing list](https://sourceforge.net/p/ddclient/mailman/message/36589979/)
--->
-
-# Index
-
-1. TOC
-{:toc}
-
-<!--
-# Important notice
-There are a few changes coming.
-
-* Because of some recent personal changes I'm not having enough time to work on this project any more.  There are only some obvious bugreports which get solved quickly but others stay there forever.
-* Dyndns decided to change their business model and [they stopped offering free account](http://www.dyndnscommunity.com/questions/21580/from-dyn-what-happened-to-free-accounts.html).  It made me decide to make dyndns less important for ddclient.
-* Sourceforge [decided to retire the hosted apps](http://sourceforge.net/blog/hosted-apps-migration-update/) which means this trac environment will come to an end.  A backup of the old trac can be found on http://ddclient.tisnix.be but all usefull data will be moved to the new environment.
--->
-
 # Introduction
 
-DDclient is a Perl client used to update dynamic DNS entries for accounts on Dynamic DNS Network Service Provider. It was originally written by Paul Burry and is now mostly by wimpunk.  It has the capability to update more than just [dyndns](http://www.dyndns.com) and it can fetch your WAN-ipaddress in a few different ways. Check the configuration pages to find how to do this.
+`ddclient` updates dynamic DNS entries for accounts on a wide range of dynamic DNS services.
 
-According to [cudeso.be](http://linux.cudeso.be/linuxdoc/ddclient.php):
-> DDclient is a small but full featured client requiring only Perl and no additional modules. It runs under most UNIX OSes and has been tested under GNU/Linux and FreeBSD. Supported features include: operating as a daemon, manual and automatic updates, static and dynamic updates, optimized updates for multiple addresses, MX, wildcards, abuse avoidance, retrying failed updates, and sending update status to syslog and through e-mail.
+This is applicable to a wide range of use cases. It's commonly used when you have an IP address that changes regularly (e.g. on a residential network), that you want to keep service pointing at (e.g. your domain name).
 
-# News
+# Installation
 
- * [Ddclient 3.9.0 released](https://github.com/ddclient/ddclient/releases/tag/v3.9.0)
+See the [GitHub README](https://github.com/ddclient/ddclient?tab=readme-ov-file#installation).
 
-You can also check [the mailinglist](https://sourceforge.net/p/ddclient/mailman/message/36589979/) to find out what's going on.
+# Configuration
 
-# Installation
-Most distributions have a recent version of ddclient.  Use it unless you really need the latest version. On debian-based systems you can run `apt-get install ddclient` and it will install ddclient.  Unless there is a good reason, you should't use the release link.
+ddclient has two primary means of configuration:
+- (Recommended) The `ddclient.conf` file, which defaults to `/etc/ddclient/ddclient.conf`.
+- Passing in arguments via [the command line](#command-line-arguments).
 
-[release link](https://github.com/ddclient/ddclient/releases){: .btn }
+There are three key pieces to configuring ddclient:
+- [General settings](./general.md)
+- [Routers](./routers.md): where should ddclient find your IP? For example, [ipify](https://www.ipify.org/), or one of 20+ others.
+- [Protocols](./protocols.md): what should ddclient update when your IP changes? For example, [DuckDNS](https://www.duckdns.org/), [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/managing-dynamic-ip-addresses/), or one of [30+ others](./protocols.md).
 
-Ddclient doesn't have an automatic installation procedure. Get the tar-file from using the download button and untar it. Copy the perl script to your favorite location (ex. /usr/sbin)
-and create a ``/etc/ddclient/ddclient.conf`` configuration file. Don't forget to create the cache directory.
+## Example
 
-If you want the bleeding edge of ddclient, you can access the latest version using svn. Instructions can be found on [the code section](/p/ddclient/code/). Or if you prefer git, you can also fork the latest version from [ddclient on github](https://github.com/ddclient/ddclient)
+A typical configuration file looks like:
 
-When upgrading just replace the ddclient file by the one from the package, read the release notes and modify the cache file.  Some distributions use other directories than the default directories used by ddclient.  If you want to reuse the old once, you will have to change the configuration.
+```
+# General config
+daemon=300
 
-# Configuration
-<!-- this should be moved to a separate wiki page -->
-If you installed ddclient by using the installer of your distribution, it probably already asked you some questions and prepared a useful config file.
+# Router
+usev4=webv4,webv4=ipify-ipv4
+
+# Protocol
+protocol=dyndns2
+login=myUsername
+password=myPassword
+myhost.dyndns.org
+```
 
-There are a few configuration examples provided which you can copy to ``/etc/ddclient/ddclient.conf`` and modify. More info about the configuration can be found on the [usage page](usage). There's also a sample configuration delivered with ddclient.
+With this config, executing `ddclient` would start a daemon that every 300 seconds would:
+1. Get your IPv4 address from the ipify web service.
+2. Login to your dyndns account with the given username and password, and update the `myhost.dyndns.org` domain to your current IPv4 address.
 
-A typical configuration like:
+You can set up `ddclient` to run on automatically using other packages on your system, such as [systemd](https://github.com/ddclient/ddclient/blob/master/sample-etc_systemd.service), [cron](https://github.com/ddclient/ddclient/blob/master/sample-etc_cron.d_ddclient), [dhclient](https://github.com/ddclient/ddclient/blob/master/sample-etc_dhclient-exit-hooks), [dhcpc](https://github.com/ddclient/ddclient/blob/master/sample-etc_dhcpc_dhcpcd-eth0.exe) and others. There are additional sample startup scripts in the [GitHub repository](https://github.com/ddclient/ddclient).
 
-    # /etc/ddclient/ddclient.conf
-    #
-    protocol=dyndns2
-    use=web
-    login=mylogin
-    password=mypassword
-    myhost.dyndns.org
+## Using environment variables
 
-You can run ddclient as ``/usr/sbin/ddclient -daemon 300 -syslog`` and put it in your startup scripts. There are samples of startup scripts provided with ddclient.  Most distributions provide a generic startup sample.  You can change it to work with ddclient.  As there are to many different distributions, ddclient doesn't maintain all of them. 
+As of version 3.11.0_1, ddclient supports using environment variables inside the configuration file. By appending '_env' to a parameter, ddclient will interpret the value of that parameter as the name of an environment variable and use the value of that environment variable as the configuration value. This allows to keep sensitive information such as the login or password outside of the configuration file.
 
-# Documentation
-<!-- keep it shorter on this place -->
-The documentation about the configuration has been split into three sections.  The [usage page](usage) describes the most parts of the configuration while the [supported protocols](protocols) page describes the protocol-specific options. If you want to know how to use ddclient with your router, check the [supported routers](routers).
+```
+login_env=DDCLIENT_LOGIN
+password_env=DDCLIENT_PASSWORD
+myhost.dyndns.org
+```
 
-Debugging ddclient looks pretty hard but it isn't. First try to put as less as necessary in your configuration. Try to run
+This example config file will use the value of the environment variables DDCLIENT_LOGIN and DDCLIENT_PASSWORD as the login and password for the domain myhost.dyndns.org respectively.
 
-    ./ddclient -daemon=0 -noquiet -debug 
+## Command-line arguments
 
-and check the result. Try to add the features you need and check it again.
+For simplicity, it's recommended you use the `ddclient.conf` file over command line arguments. If you can't use the default location, you can use the `file` argument only to read config from a different file, e.g. `ddclient -file ddclientCustom.conf`
 
-Once you're happy with the result, run it as a daemon.
+However, any arguments can also be provided via the command line when invoking ddclient. For example:
 
-If this doesn't work for you, there are a few places where you can look for help. If you need any help in configuring ddclient,
-You could try ddclient --help. It should give you all the possible configuration options so.
+```
+ddclient -daemon 300 -protocol dyndns2 -login myUsername -password myPassword myhost.dyndns.org
+```
 
-If you think your configuration is correct, but ddclient doesn't work as you expected, you can enable debug and verbose messages by running
+ddclient prioritizes command line arguments, then falls back to `ddclient.conf`, then falls back to in-built defaults.
 
-    ddclient -daemon=0 -debug -verbose -noquiet
+# Support
 
-We know the manual is not very clear, you have to read the example configurations included in the tar-file or you can run ``ddclient --help`` to get more help.
+If you need extra help, want to report a bug, or submit a feature request, [create a GitHub issue](https://github.com/ddclient/ddclient/issues/new). Before posting, check it is not a duplicate and the problem is present on the latest version of ddclient.
 
-# Help and bugreporting
-If you need extra help, have any bug to report, an enhancement to submit or a feature request, you can use the [ddclient mailing list](https://lists.sourceforge.net/lists/listinfo/ddclient-support) or [create a new issue](https://github.com/ddclient/ddclient/issues/new).  Please only post bugs against the latest version of ddclient.
-If you want to provide a patch for ddclient, please use a pull request on github.  It's the easiest way of working.
+If you want to contribute code to ddclient, raise a pull request on GitHub.