From 3787ad12df17b81a28b5397232219e0410056173 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Wed, 3 Jul 2024 10:25:52 +0200 Subject: [PATCH] Update help/docs and actually make it possible to add more than one argument --- README.md | 79 ++++++++++++++++++++++++++++++++++++++---- knotctl/__init__.py | 83 ++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 146 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ec979e1..eb91004 100644 --- a/README.md +++ b/README.md @@ -51,8 +51,10 @@ source <(knotctl completion) ## Usage ``` -usage: knotctl [-h] [--json | --no-json] - {add,completion,config,delete,list,update} ... +usage: knotctl [-h] [--json | --no-json] {add,completion,config,delete,list,update} ... + +Manage DNS records with knot dns rest api: + * https://gitlab.nic.cz/knot/knot-dns-rest positional arguments: {add,completion,config,delete,list,update} @@ -60,6 +62,48 @@ positional arguments: options: -h, --help show this help message and exit --json, --no-json + + The Domain Name System specifies a database of information + elements for network resources. The types of information + elements are categorized and organized with a list of DNS + record types, the resource records (RRs). Each record has a + name, a type, an expiration time (time to live), and + type-specific data. + + The following is a list of terms used in this program: + ---------------------------------------------------------------- + | Vocabulary | Description | + ---------------------------------------------------------------- + | zone | A DNS zone is a specific portion of the DNS | + | | namespace in the Domain Name System (DNS), | + | | which a specific organization or administrator | + | | manages. | + ---------------------------------------------------------------- + | name | In the Internet, a domain name is a string that | + | | identifies a realm of administrative autonomy, | + | | authority or control. Domain names are often | + | | used to identify services provided through the | + | | Internet, such as websites, email services and | + | | more. | + ---------------------------------------------------------------- + | rtype | A record type indicates the format of the data | + | | and it gives a hint of its intended use. For | + | | example, the A record is used to translate from | + | | a domain name to an IPv4 address, the NS record | + | | lists which name servers can answer lookups on | + | | a DNS zone, and the MX record specifies the | + | | mail server used to handle mail for a domain | + | | specified in an e-mail address. | + ---------------------------------------------------------------- + | data | A records data is of type-specific relevance, | + | | such as the IP address for address records, or | + | | the priority and hostname for MX records. | + ---------------------------------------------------------------- + + This information was compiled from Wikipedia: + * https://en.wikipedia.org/wiki/DNS_zone + * https://en.wikipedia.org/wiki/Domain_Name_System + * https://en.wikipedia.org/wiki/Zone_file ``` ### ADD @@ -67,6 +111,8 @@ options: ``` usage: knotctl add [-h] -d DATA -n NAME -r RTYPE [-t TTL] -z ZONE +Add a new record to the zone. + options: -h, --help show this help message and exit -d DATA, --data DATA @@ -81,6 +127,8 @@ options: ``` usage: knotctl completion [-h] [-s SHELL] +Generate shell completion script. + options: -h, --help show this help message and exit -s SHELL, --shell SHELL @@ -89,12 +137,14 @@ options: ### CONFIG ``` -usage: knotctl config [-h] [-c CONTEXT] [-b BASEURL] [-p PASSWORD] [-u USERNAME] +usage: knotctl config [-h] [-b BASEURL] [-c CONTEXT] [-p PASSWORD] [-u USERNAME] + +Configure access to knot-dns-rest-api. options: -h, --help show this help message and exit - -c CONTEXT, --context CONTEXT -b BASEURL, --baseurl BASEURL + -c CONTEXT, --context CONTEXT -p PASSWORD, --password PASSWORD -u USERNAME, --username USERNAME ``` @@ -104,6 +154,8 @@ options: ``` usage: knotctl delete [-h] [-d DATA] [-n NAME] [-r RTYPE] -z ZONE +Delete a record from the zone. + options: -h, --help show this help message and exit -d DATA, --data DATA @@ -115,7 +167,9 @@ options: ### LIST ``` -usage: knotctl list [-h] [-d DATA] [-n NAME] [-r RTYPE] [-z ZONE] +usage: knotctl list [-h] [-d DATA] [-n NAME] [-r RTYPE] -z ZONE + +List records in the zone. options: -h, --help show this help message and exit @@ -130,15 +184,26 @@ options: ``` usage: knotctl update [-h] -a [ARGUMENT ...] -d DATA -n NAME -r RTYPE [-t TTL] -z ZONE +Update a record in the zone. The record must exist in the zone. +In this case --data, --name, --rtype and --ttl switches are used +for searching for the appropriate record, while the --argument +switches are used for updating the record. options: -h, --help show this help message and exit - -a [ARGUMENT ...], --argument [ARGUMENT ...] + -a [KEY=VALUE ...], --argument [KEY=VALUE ...] Specify key - value pairs to be updated: - name=dns1.example.com. + name=dns1.example.com. or data=127.0.0.1 for example. + --argument can be repeated -d DATA, --data DATA -n NAME, --name NAME -r RTYPE, --rtype RTYPE -t TTL, --ttl TTL -z ZONE, --zone ZONE + +Available arguments are: + data: New record data. + name: New record domain name. + rtype: New record type. + ttl: New record time to live (TTL). ``` diff --git a/knotctl/__init__.py b/knotctl/__init__.py index 8768c51..2ff7347 100755 --- a/knotctl/__init__.py +++ b/knotctl/__init__.py @@ -246,44 +246,108 @@ def split_url(url: str) -> dict: # Entry point to program def main() -> int: + description = """Manage DNS records with knot dns rest api: + * https://gitlab.nic.cz/knot/knot-dns-rest""" + + epilog = """ + The Domain Name System specifies a database of information + elements for network resources. The types of information + elements are categorized and organized with a list of DNS + record types, the resource records (RRs). Each record has a + name, a type, an expiration time (time to live), and + type-specific data. + + The following is a list of terms used in this program: + ---------------------------------------------------------------- + | Vocabulary | Description | + ---------------------------------------------------------------- + | zone | A DNS zone is a specific portion of the DNS | + | | namespace in the Domain Name System (DNS), | + | | which a specific organization or administrator | + | | manages. | + ---------------------------------------------------------------- + | name | In the Internet, a domain name is a string that | + | | identifies a realm of administrative autonomy, | + | | authority or control. Domain names are often | + | | used to identify services provided through the | + | | Internet, such as websites, email services and | + | | more. | + ---------------------------------------------------------------- + | rtype | A record type indicates the format of the data | + | | and it gives a hint of its intended use. For | + | | example, the A record is used to translate from | + | | a domain name to an IPv4 address, the NS record | + | | lists which name servers can answer lookups on | + | | a DNS zone, and the MX record specifies the | + | | mail server used to handle mail for a domain | + | | specified in an e-mail address. | + ---------------------------------------------------------------- + | data | A records data is of type-specific relevance, | + | | such as the IP address for address records, or | + | | the priority and hostname for MX records. | + ---------------------------------------------------------------- + + This information was compiled from Wikipedia: + * https://en.wikipedia.org/wiki/DNS_zone + * https://en.wikipedia.org/wiki/Domain_Name_System + * https://en.wikipedia.org/wiki/Zone_file + """ # Grab user input - parser = argparse.ArgumentParser() + parser = argparse.ArgumentParser(description=description, epilog=epilog, formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument("--json", action=argparse.BooleanOptionalAction) subparsers = parser.add_subparsers(dest="command") - addcmd = subparsers.add_parser("add") + + add_description = "Add a new record to the zone." + addcmd = subparsers.add_parser("add", description=add_description) addcmd.add_argument("-d", "--data", required=True) addcmd.add_argument("-n", "--name", required=True) addcmd.add_argument("-r", "--rtype", required=True) addcmd.add_argument("-t", "--ttl") addcmd.add_argument("-z", "--zone", required=True) - completecmd = subparsers.add_parser("completion") + complete_description = "Generate shell completion script." + completecmd = subparsers.add_parser("completion", description=complete_description) completecmd.add_argument("-s", "--shell") - configcmd = subparsers.add_parser("config") + config_description = "Configure access to knot-dns-rest-api." + configcmd = subparsers.add_parser("config", description=config_description) configcmd.add_argument("-b", "--baseurl") configcmd.add_argument("-c", "--context") configcmd.add_argument("-p", "--password") configcmd.add_argument("-u", "--username") - deletecmd = subparsers.add_parser("delete") + delete_description = "Delete a record from the zone." + deletecmd = subparsers.add_parser("delete", description=delete_description) deletecmd.add_argument("-d", "--data") deletecmd.add_argument("-n", "--name") deletecmd.add_argument("-r", "--rtype") deletecmd.add_argument("-z", "--zone", required=True) - listcmd = subparsers.add_parser("list") + list_description = "List records in the zone." + listcmd = subparsers.add_parser("list", description=list_description) listcmd.add_argument("-d", "--data") listcmd.add_argument("-n", "--name") listcmd.add_argument("-r", "--rtype") listcmd.add_argument("-z", "--zone", required=True) - updatecmd = subparsers.add_parser("update") + update_description = "Update a record in the zone. The record must exist in the zone.\n" + update_description += "In this case --data, --name, --rtype and --ttl switches are used\n" + update_description += "for searching for the appropriate record, while the --argument\n" + update_description += "switches are used for updating the record." + update_epilog = """Available arguments are: + data: New record data. + name: New record domain name. + rtype: New record type. + ttl: New record time to live (TTL).""" + updatecmd = subparsers.add_parser("update", description=update_description, epilog=update_epilog, formatter_class=argparse.RawDescriptionHelpFormatter ) updatecmd.add_argument( "-a", "--argument", nargs="*", - help="Specify key - value pairs to be updated: name=dns1.example.com.", + action="append", + metavar="KEY=VALUE", + help= + "Specify key - value pairs to be updated: name=dns1.example.com. or data=127.0.0.1 for example. --argument can be repeated", required=True, ) updatecmd.add_argument("-d", "--data", required=True) @@ -306,7 +370,8 @@ def main() -> int: mkdir(config_basepath) if args.command == "config": - run_config(config_filename, args.context, args.baseurl, args.username, args.password) + run_config(config_filename, args.context, args.baseurl, args.username, + args.password) return 0 if not isfile(config_filename):