From 1c5fa1c28dd36e1f63dfe341eeb857660eef503a Mon Sep 17 00:00:00 2001 From: Martin Basti Date: Wed, 2 Jul 2014 15:56:29 +0200 Subject: Split dns docstring Reviewed-By: Petr Spacek --- ipalib/plugins/dns.py | 94 +++++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 47 deletions(-) (limited to 'ipalib') diff --git a/ipalib/plugins/dns.py b/ipalib/plugins/dns.py index 97d8dc168..e8e4e33a1 100644 --- a/ipalib/plugins/dns.py +++ b/ipalib/plugins/dns.py @@ -48,23 +48,23 @@ from ipapython.dnsutil import DNSName __doc__ = _(""" Domain Name System (DNS) - +""") + _(""" Manage DNS zone and resource records. - +""") + _(""" SUPPORTED ZONE TYPES * Master zone (dnszone-*), contains authoritative data. * Forward zone (dnsforwardzone-*), forwards queries to configured forwarders (a set of DNS servers). - +""") + _(""" USING STRUCTURED PER-TYPE OPTIONS - +""") + _(""" There are many structured DNS RR types where DNS data stored in LDAP server is not just a scalar value, for example an IP address or a domain name, but a data structure which may be often complex. A good example is a LOC record [RFC1876] which consists of many mandatory and optional parts (degrees, minutes, seconds of latitude and longitude, altitude or precision). - +""") + _(""" It may be difficult to manipulate such DNS records without making a mistake and entering an invalid value. DNS module provides an abstraction over these raw records and allows to manipulate each RR type with specific options. For @@ -72,7 +72,7 @@ each supported RR type, DNS module provides a standard option to manipulate a raw records with format ---rec, e.g. --mx-rec, and special options for every part of the RR structure with format ---, e.g. --mx-preference and --mx-exchanger. - +""") + _(""" When adding a record, either RR specific options or standard option for a raw value can be used, they just should not be combined in one add operation. When modifying an existing entry, new RR specific options can be used to change @@ -81,41 +81,41 @@ to specify the modified value. The following example demonstrates a modification of MX record preference from 0 to 1 in a record without modifying the exchanger: ipa dnsrecord-mod --mx-rec="0 mx.example.com." --mx-preference=1 - +""") + _(""" EXAMPLES: - +""") + _(""" Add new zone: ipa dnszone-add example.com --name-server=ns \\ --admin-email=admin@example.com \\ --ip-address=192.0.2.1 - +""") + _(""" Add system permission that can be used for per-zone privilege delegation: ipa dnszone-add-permission example.com - +""") + _(""" Modify the zone to allow dynamic updates for hosts own records in realm EXAMPLE.COM: ipa dnszone-mod example.com --dynamic-update=TRUE - +""") + _(""" This is the equivalent of: ipa dnszone-mod example.com --dynamic-update=TRUE \\ --update-policy="grant EXAMPLE.COM krb5-self * A; grant EXAMPLE.COM krb5-self * AAAA; grant EXAMPLE.COM krb5-self * SSHFP;" - +""") + _(""" Modify the zone to allow zone transfers for local network only: ipa dnszone-mod example.com --allow-transfer=192.0.2.0/24 - +""") + _(""" Add new reverse zone specified by network IP address: ipa dnszone-add --name-from-ip=192.0.2.0/24 \\ --name-server=ns.example.com. - +""") + _(""" Add second nameserver for example.com: ipa dnsrecord-add example.com @ --ns-rec=nameserver2.example.com - +""") + _(""" Add a mail server for example.com: ipa dnsrecord-add example.com @ --mx-rec="10 mail1" - +""") + _(""" Add another record using MX record specific options: ipa dnsrecord-add example.com @ --mx-preference=20 --mx-exchanger=mail2 - +""") + _(""" Add another record using interactive mode (started when dnsrecord-add, dnsrecord-mod, or dnsrecord-del are executed with no options): ipa dnsrecord-add example.com @ @@ -128,28 +128,28 @@ EXAMPLES: Record name: example.com MX record: 10 mail1, 20 mail2, 30 mail3 NS record: nameserver.example.com., nameserver2.example.com. - +""") + _(""" Delete previously added nameserver from example.com: ipa dnsrecord-del example.com @ --ns-rec=nameserver2.example.com. - +""") + _(""" Add LOC record for example.com: ipa dnsrecord-add example.com @ --loc-rec="49 11 42.4 N 16 36 29.6 E 227.64m" - +""") + _(""" Add new A record for www.example.com. Create a reverse record in appropriate reverse zone as well. In this case a PTR record "2" pointing to www.example.com will be created in zone 2.0.192.in-addr.arpa. ipa dnsrecord-add example.com www --a-rec=192.0.2.2 --a-create-reverse - +""") + _(""" Add new PTR record for www.example.com ipa dnsrecord-add 2.0.192.in-addr.arpa. 2 --ptr-rec=www.example.com. - +""") + _(""" Add new SRV records for LDAP servers. Three quarters of the requests should go to fast.example.com, one quarter to slow.example.com. If neither is available, switch to backup.example.com. ipa dnsrecord-add example.com _ldap._tcp --srv-rec="0 3 389 fast.example.com" ipa dnsrecord-add example.com _ldap._tcp --srv-rec="0 1 389 slow.example.com" ipa dnsrecord-add example.com _ldap._tcp --srv-rec="1 1 389 backup.example.com" - +""") + _(""" The interactive mode can be used for easy modification: ipa dnsrecord-mod example.com _ldap._tcp No option to modify specific record provided. @@ -166,10 +166,10 @@ EXAMPLES: 1 SRV record skipped. Only one value per DNS record type can be modified at one time. Record name: _ldap._tcp SRV record: 0 3 389 fast.example.com, 1 1 389 backup.example.com, 0 2 389 slow.example.com - +""") + _(""" After this modification, three fifths of the requests should go to fast.example.com and two fifths to slow.example.com. - +""") + _(""" An example of the interactive mode for dnsrecord-del command: ipa dnsrecord-del example.com www No option to delete specific record provided. @@ -182,33 +182,33 @@ EXAMPLES: Delete A record '192.0.2.3'? Yes/No (default No): y Record name: www A record: 192.0.2.2 (A record 192.0.2.3 has been deleted) - +""") + _(""" Show zone example.com: ipa dnszone-show example.com - +""") + _(""" Find zone with "example" in its domain name: ipa dnszone-find example - +""") + _(""" Find records for resources with "www" in their name in zone example.com: ipa dnsrecord-find example.com www - +""") + _(""" Find A records with value 192.0.2.2 in zone example.com ipa dnsrecord-find example.com --a-rec=192.0.2.2 - +""") + _(""" Show records for resource www in zone example.com ipa dnsrecord-show example.com www - +""") + _(""" Delegate zone sub.example to another nameserver: ipa dnsrecord-add example.com ns.sub --a-rec=203.0.113.1 ipa dnsrecord-add example.com sub --ns-rec=ns.sub.example.com. - +""") + _(""" Delete zone example.com with all resource records: ipa dnszone-del example.com - +""") + _(""" If a global forwarder is configured, all queries for which this server is not authoritative (e.g. sub.example.com) will be routed to the global forwarder. Global forwarding configuration can be overridden per-zone. - +""") + _(""" Semantics of forwarding in IPA matches BIND sematics and depends on type of the zone: * Master zone: local BIND replies authoritatively to queries for data in @@ -219,55 +219,55 @@ EXAMPLES: * Forward zone: forward zone contains no authoritative data. BIND forwards queries, which cannot be answered from its local cache, to configured forwarders. - +""") + _(""" Semantics of the --forwarder-policy option: * none - disable forwarding for the given zone. * first - forward all queries to configured forwarders. If they fail, do resolution using DNS root servers. * only - forward all queries to configured forwarders and if they fail, return failure. - +""") + _(""" Disable global forwarding for given sub-tree: ipa dnszone-mod example.com --forward-policy=none - +""") + _(""" This configuration forwards all queries for names outside the example.com sub-tree to global forwarders. Normal recursive resolution process is used for names inside the example.com sub-tree (i.e. NS records are followed etc.). - +""") + _(""" Forward all requests for the zone external.example.com to another forwarder using a "first" policy (it will send the queries to the selected forwarder and if not answered it will use global root servers): ipa dnsforwardzone-add external.example.com --forward-policy=first \\ --forwarder=203.0.113.1 - +""") + _(""" Change forward-policy for external.example.com: ipa dnsforwardzone-mod external.example.com --forward-policy=only - +""") + _(""" Show forward zone external.example.com: ipa dnsforwardzone-show external.example.com - +""") + _(""" List all forward zones: ipa dnsforwardzone-find - +""") + _(""" Delete forward zone external.example.com: ipa dnsforwardzone-del external.example.com - +""") + _(""" Resolve a host name to see if it exists (will add default IPA domain if one is not included): ipa dns-resolve www.example.com ipa dns-resolve www - +""") + _(""" GLOBAL DNS CONFIGURATION - +""") + _(""" DNS configuration passed to command line install script is stored in a local configuration file on each IPA server where DNS service is configured. These local settings can be overridden with a common configuration stored in LDAP server: - +""") + _(""" Show global DNS configuration: ipa dnsconfig-show - +""") + _(""" Modify global DNS configuration and set a list of global forwarders: ipa dnsconfig-mod --forwarder=203.0.113.113 """) -- cgit