public/freeipa
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Split dns docstring

Browse Source 
Reviewed-By: Petr Spacek <pspacek@redhat.com>
This commit is contained in:
Martin Basti authored and Petr Viktorin committed 2014-07-03 10:32:09 +02:00
1 parent d22d971575
commit 1c5fa1c28d
1 file changed
+47 -47
Download Patch File Download Diff File Expand all files Collapse all files
ipalib/plugins/dns.py
+47 -47
View File
@@ -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 --<rrtype>-rec, e.g. --mx-rec, and special options
for every part of the RR structure with format --<rrtype>-<partname>, 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
""")