From f6719cee968d334603b07883a8afbc146a80026e Mon Sep 17 00:00:00 2001 From: Michael Tremer Date: Thu, 25 Sep 2014 14:50:27 +0200 Subject: [PATCH] Improve man pages --- .gitignore | 2 ++ man/ddns.conf.xml | 79 +++++++++++++++++++++++-------------------- man/ddns.xml | 85 +++++++++++++++-------------------------------- 3 files changed, 71 insertions(+), 95 deletions(-) diff --git a/.gitignore b/.gitignore index dc5d2d3..29e653d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,8 @@ /build-aux /ddns /ddns.conf +/man/*.[0-9] +/man/*.html /missing /src/ddns/__version__.py /tmp diff --git a/man/ddns.conf.xml b/man/ddns.conf.xml index a00ccc6..9b113bc 100644 --- a/man/ddns.conf.xml +++ b/man/ddns.conf.xml @@ -14,6 +14,13 @@ Schantl stefan.schantl@ipfire.org + + + Developer + Michael + Tremer + michael.tremer@ipfire.org + @@ -24,21 +31,24 @@ ddns.conf - Configuration file for the DDNS update client. + Configuration file for the DDNS update client Description - The ddns.conf file is the main configuration file for the - ddns update client. This file specifies some basic options - for the programm and contain multiple sections which imply hostname and auth information - for each used provider. + The ddns.conf file is the main configuration file of the + ddns update client. + This file specifies runtime configuration parameters for the programm and + contains configurations for dynamic host entries that are managed by + ddns. - Lines starting with a hash mark (''#'') and empty lines are ignored. + The syntax of the configuration file is based on the INI configuration + file format. Lines starting with hash (#) or semi-colon (;) + are ignored. @@ -57,24 +67,21 @@ - Using this option allows the usage of a proxy server while - performing updates. + This option will configure the HTTP proxy server that is used to + communicate with the providers HTTP APIs. The proxy only can be contacted by using the HTTP protocol. The - server has to be specified by using its IP address and the used port. - - - - Example: proxy = http://192.168.180.1:800 + server has to be specified by using its IP address and port. + For example: - + @@ -83,8 +90,9 @@ - The default value if this setting is not configured is - true. + By default, this option is disabled and automatically enabled + if the client has only IP addresses defined in RFC1918 or + other reserved address space. @@ -95,9 +103,9 @@ Provider Configuration - The DDNS client supports the configuration of an unlimited amount of entries on different providers. - Each entry has to be configured as an own section which has to be initiated with the choosen FQDN - (Fully Qualified Domain Name) inside of squared brackets. + The DDNS client supports the configuration of an unlimited amount of entries for different providers. + Each entry has to be configured as an own section named by the FQDN (Fully Qualified Domain Name) + inside squared brackets. @@ -108,8 +116,9 @@ - Specifies the choosen FQDN composed of the hostname and the selected domain from the - desired dynamic DNS provider. + The FQDN of the dynamic host. This name will be resolved + by ddns and therfore must not be a handle or something + other than a FQDN. @@ -121,12 +130,12 @@ - The provider which is responsible for the configured FQDN. + The provider which is responsible for this host. - A list of all supported providers can be found in the ddns.conf.sample - or the README file shipped by the source code. + A list of all supported providers can be looked up by running + ddns list-providers. @@ -138,19 +147,19 @@ - The used username to authenticate against your providers update service. + The username to authenticate against the provider's update service. In most cases this will be the same username which can be used to login on - your providers webpage. + your provider's web page. - password = pass + password = password @@ -167,12 +176,14 @@ - Just the authentication token. + An authentication token. - If your dynamic DNS provider supports token-based auth, this method should - be prefered. + If your dynamic DNS provider supports token-based authentication, + this method should be prefered. + You do not need to specify the username if token-based authentication + is used. @@ -183,7 +194,7 @@ Examples - A provider which uses username and password for client authentication. + For providers which use username and password for client authentication [somehost.provider.com] @@ -194,7 +205,7 @@ - Provider which supports token based auth. + For providers which supports token-based authentication [anotherhost.provider.com] @@ -221,10 +232,6 @@ ddns 1 - - ddns-devel - 7 - diff --git a/man/ddns.xml b/man/ddns.xml index 05f429a..dda4b94 100644 --- a/man/ddns.xml +++ b/man/ddns.xml @@ -14,6 +14,13 @@ Schantl stefan.schantl@ipfire.org + + + Developer + Michael + Tremer + michael.tremer@ipfire.org + @@ -87,9 +94,7 @@ - Enables the debugging mode. - In this mode, there will be debug output on - the console and written to the log. + Enables the debugging output. @@ -119,21 +124,10 @@ - - - update-all - - - - - Update all configured dynamic DNS hosts. - - - - update HOSTNAME + update HOSTNAME @@ -143,32 +137,34 @@ - Example: ddns update somehost.provider.com + When calling an update, the DDNS client automatically checks + if this update is required by testing whether the hostname points + to the current public IP address. + Therefore it is not guaranteed than an update is performed. + + + + The switch can be used to skip that + check and perform an update. Please note that some providers + may block your account if unnecessary updates are repeatedly + performed. - + update-all - When calling an update, the DDNS client automatically checks - if this update is required by testing whether the hostname points - to the current public IP address. If this test returns true, the call - can be droped and no request will be sent to the provider. - - - - In cases an update request should be send nevertheless, the update can be - forced by using this switch. + Update all configured dynamic DNS hosts when an update is necessary. - Example: ddns update somehost.provider.com --force or - ddns update-all --force + The switch has the same effect as + with the update command. @@ -180,24 +176,9 @@ - Try to guess and print the hosts IPv4 and IPv6 addresses - based on the choosen method in the used config file. + Guesses the public IPv6 and IPv4 addresses with help of an + external server and prints them on the conole. - - - The addresses can be obtained from the system or by - help of an external server. For systems behind a NAT the - second method is recommended. - - - - For further details, please consult the - - ddns.conf - 5 - - manual page. - @@ -211,16 +192,6 @@ This command will print out a list of all supported dynamic DNS providers. - - - For details how to add support for new providers, - please consult the - - ddns-devel - 7 - - manual page. - @@ -252,10 +223,6 @@ ddns.conf 5 - , - - ddns-devel - 7 -- 2.39.2