diff --git a/doc/dnsserial.txt b/doc/dnsserial.txt new file mode 100644 index 0000000..489349c --- /dev/null +++ b/doc/dnsserial.txt @@ -0,0 +1,147 @@ +*dnsserial.txt* another DNS-zone serial number updater + + ____ _ _ ____ _ _ ~ + | _ \| \ | / ___| ___ ___ _ __(_) __ _| |~ + | | | | \| \___ \/ __|/ _ \ '__| |/ _` | |~ + | |_| | |\ |___) \__ \ __/ | | | (_| | |~ + |____/|_| \_|____/|___/\___|_| |_|\__,_|_|~ + + Another DNS-zone serial number updater. + +============================================================================== +CONTENTS *DNSserialContents* + + 1. Introduction ......... |DNSserial| + 2. Usage ................ |DNSserialUsage| + 3. Patterns ............. |DNSserialPatterns| + 4. Configuration ........ |DNSserialConfiguration| + 5. Custom patterns ...... |DNSserialCustomPatterns| + 5.1 regex ........... |DNSserialCustomPatterns-regex| + 5.2 matching ........ |DNSserialCustomPatterns-matching| + 5.3 examples ........ |DNSserialCustomPatterns-examples| + 6. License .............. |DNSserialLicense| + +============================================================================== +Section 1: Introduction *DNSserial* + +I know this not the first vim plugin available to update a DNS-zone serial +number. Here is a few reasons why I chose not to use the canonical one: + + - there is no license and therefore it is not free; + - it is unmaintained; + - it is bugged; + - it lacks functionalities. + +It chose not to fork the original plugin but to write a new one from scratch +mainly for legal purposes, but also because I did not found the code as simple +as I expected. + +============================================================================== +Section 2: Usage *DNSserialUsage* + +By default, each time you save a bindzone file, the script will look for the +DNS serial number and update it. You can also update it without saving the +file by invoking the :DNSSerialUpdate function. + +============================================================================== +Section 3: Patterns *DNSserialPatterns* + +In order to be detected, the DNS serial number must match one the following +pattern: + + - YYYYMMDDXX ; serial + * YYYY is the year (4 digits, must start by either 19 or 2); + * MM is the month (2 digits); + * DD is the day (2 digits); + * XX is any non-negative number (1 or more digits); + * the word serial is not case-sensitive; + * there can be any number of blanks on each sides of the semicolon. + + - SSSSSSSSSS ; serial + * SSSSSSSSSS is the UNIX tiemstamp (10 digits, must start by 1); + * the word serial is not case-sensitive; + * there can be any number of blanks on each sides of the semicolon. + + - XX ; serial + * XX is any non-negative number (1 or more digits); + * the word serial is not case-sensitive; + * there can be any number of blanks on each sides of the semicolon. + +According to those patterns, only dates between 1900 and 2999 will be +detected; however this should not be a problem at all. Most importantly, only +timestamps between September 9 2001 and March 17 2030 will be detected. + +============================================================================== +Section 4: Configuration *DNSserialConfiguration* + +You can set several configuration variables in your vimrc: + + - g:dnsserial_auto_update: Defines whether or not the serial is updated when + the zone file is saved (default is 1, set it to 0 to disable). + - g:dnsserial_custom_patterns: List of customs patterns that will be added to + the default ones. Order matters, the first matching patters will be used. + Customs patterns will be tested before the default ones. + - g:dnsserial_patterns: List of default patterns. It is not advised to change + it. + +============================================================================== +Section 5: Custom patterns *DNSserialCustomPatterns* + +A pattern is defined by a dictionary with two keys: regex and matching. + +------------------------------------------------------------------------------ +Section 5.1: regex *DNSserialCustomPatterns-regex* + +Contains the regular expression that will be used to search the document for +the serial number. All the components of the serial number must be captured +with parenthesis. + +------------------------------------------------------------------------------ +Section 5.1: matching *DNSserialCustomPatterns-matching* + +This is a list of every components of the serial number. Each component is +defined by a dictionary. The type key must be present and contain one of the +allowed types. Depending on the type, several additional keys might be +defined. Authorized types and their options are: + + - raw: Raw string. + - integer: An integer that will be incremented. + - offset (int): set the offset by which the integer is incremented. Default + is 1. + - padding (int): Force the integer to be 0-padded on the associated number of + digits. + - date_reset (bool): If set to 1 and a the serial contains a date, the + integer will be reseted to 0 if the date is updated. Default is 0. + - date: A formated date that will be updated to the current one. + - fmt (string, mandatory) : the date format according to the strftime() + specifications. See :help strftime for more details. + +------------------------------------------------------------------------------ +Section 5.1: examples *DNSserialCustomPatterns-examples* + +A simple pattern matching a serial defined as an integer and followed by a +comment starting by the word serial is: + + { + 'regex': '\(\d\+\)\s*;\s*\cserial', + 'matching': [ + {'type': 'integer'} + ] + } + +The same example, but having the serial number starting by the current date +(YYYYMMDD) and the integer padded on two digits: + + { + 'regex': '\(\d\{8}\)\(\d\+\)\s*;\s*\cserial', + 'matching': [ + {'type': 'date', 'fmt': '%Y%m%d'}, + {'type': 'integer', 'padding': 2, 'date_reset': 1} + ] + } + +============================================================================== +Section 6: License *DNSserialLicense* + +DNSserial is Copyright 2015 Rodolphe Breard and is licensed under the Apache +License, Version 2.0.