Changeset 765

Timestamp:

06/23/17 13:01:18 (8 years ago)

Author:

Kris Deugau

Message:

/trunk

Commit long-pending POD addition to dns-rpc.cgi

File:

• trunk/dns-rpc.cgi (modified) (34 diffs)

trunk/dns-rpc.cgi

@@ -134 +134 @@
 exit;
 
+
+=head1 dns-rpc.cgi
+
+The RPC API for DeepNet DNS Administrator.
+
+=head2 Common required arguments
+
+A few arguments for primitive authorization are required on all calls.
+
+=over 4
+
+=item rpcuser
+
+A string identifying the remote user in some way.  Used to generate a hidden local user for logging.
+
+=item rpcsystem
+
+A string identifying the remote system doing the RPC call.  This is checked against a list of IPs allowed to 
+claim this system identifier.
+
+=back
+
+=cut
+
 ##
 ## Subs below here
@@ -214 +238 @@
 ## Shims for DNSDB core subs
 ##
+
+
+=head2 Exposed RPC subs
+
+=cut
+#over 4
+
 
 #sub connectDB {
@@ -225 +256 @@
 #sub _log {
 
+
+=head3 addDomain
+
+Add a domain.  Note that while this should accept a formal .arpa reverse zone name, doing so will disrupt 
+several features that ease management of bulk reverse records.  Use C<addRDNS> to add reverse zones.
+
+=over 4
+
+=item domain
+
+The domain to add.
+
+=item group
+
+The group ID to add the domain to.  Group ID 1 is expected to exist;  otherwise a list of groups should be 
+retrieved with C<getGroupList> for selection.  The group defines which template records will be used to create 
+the initial record set in the domain.
+
+=item state
+
+Active/inactive flag.  Send C<active>, C<on>, or C<1> for domains that should be published;  C<inactive>, 
+C<off>, or C<0> for domains that should be added but not currently published.
+
+=item defloc
+
+Optional argument for the default location/view the domain's records should be published in.  Leave blank, or a 
+list of locations can be retrieved with C<getLocList> or C<getLocDropdown> for selection.
+
+=back
+
+Returns the ID of the domain.
+
+=cut
 sub addDomain {
   my %args = @_;
@@ -235 +299 @@
 }
 
+
+=head3 delZone
+
+Delete a domain or reverse zone
+
+=over 4
+
+=item zone
+
+The domain name, domain ID, .arpa zone name, or logical CIDR range to remove
+
+=item revrec
+
+Flag to indicate whether to go looking for a domain or a reverse zone to delete.  Accepts "y" or "n".
+
+=back
+
+Returns an informational confirmation message on success.
+
+=cut
 sub delZone {
   my %args = @_;
@@ -258 +342 @@
 } # delZone()
 
+
 #sub domainName {}
 #sub revName {}
 
+
+=head3 domainID
+
+Retrieve the ID for a domain
+
+=over 4
+
+=item domain
+
+The domain name to find the ID for
+
+=back
+
+Returns the integer ID of the domain if found.
+
+=cut
 sub domainID {
   my %args = @_;
@@ -273 +374 @@
 #sub revID {}
 
+
+=head3 addRDNS
+
+Add a reverse zone
+
+=over 4
+
+=item revzone
+
+The logical reverse zone to be added.  Can be specified as either formal .arpa notation or a valid CIDR 
+netblock.  Using a CIDR netblock allows logical aggregation of related records even if the CIDR range covers 
+multiple formal .arpa zone boundaries.  For example, the logical zone 192.168.4.0/22 covers 
+4.168.192.in-addr.arpa, 5.168.192.in-addr.arpa, 6.168.192.in-addr.arpa, and 7.168.192.in-addr.arpa, and will be 
+correctly published as such.
+
+=item revpatt
+
+A string representing the pattern to use for an initial template record.
+
+=item group
+
+The group ID to add the zone to.
+
+=item state
+
+Active/inactive flag.  Send C<active>, C<on>, or 1 for zones that should be published;  C<inactive>, 
+C<off>, or C<0> for zones that should be added but not currently published.
+
+=item defloc
+
+Optional argument for the default location/view the zone's records should be published in.  Leave blank, or a 
+list of locations can be retrieved with C<getLocList> or C<getLocDropdown> for selection.
+
+=back
+
+Returns the zone ID on success.
+
+=cut
 sub addRDNS {
   my %args = @_;
@@ -287 +426 @@
 #sub getZoneLocation {}
 
+
+=head3 addGroup
+
+Add a group
+
+=over 4
+
+=item groupname
+
+The name for the new group
+
+=item parent_id
+
+The ID of the group to put the new group in
+
+=back
+
+Note that the RPC API does not currently expose the full DNSDB::addGroup interface;  the permissions hashref is 
+substituted with a reasonable standard default user permissions allowing users to add/edit/delete zones and 
+records.
+
+Returns literal 'OK' on success.
+
+=cut
 sub addGroup {
   my %args = @_;
@@ -305 +468 @@
 }
 
+
+=head3 delGroup
+
+Delete a group.  The group must be empty of users, zones, or subgroups.
+
+=over 4
+
+=item group
+
+The group name or group ID to delete
+
+=back
+
+Returns an informational message on success.
+
+=cut
 sub delGroup {
   my %args = @_;
@@ -330 +509 @@
 #sub groupID {}
 
+
+=head3 addUser
+
+Add a user.
+
+=over 4
+
+=item username
+
+The username to add
+
+=item group
+
+The group ID to add the user in.  Users in subgroups only have access to data in that group and its subgroups.
+
+=item pass
+
+The password for the account
+
+=item state
+
+Flag to indicate if the account should be active on creation or set to inactive.  Accepts the same values as 
+domains and reverse zones - C<active>, C<on>, or C<1> for an active user, C<inactive>, C<off>, or C<0> for an 
+inactive one.
+
+=back
+
+B<Optional arguments>
+
+=over 4
+
+=item type
+
+Type of user account to add.  Current types are C<u> (normal user) and C<s> (superuser).  Defaults to C<u>.
+
+=item permstring
+
+A string encoding the permissions a normal user receives.  By default this is set to C<i> indicating
+permissions are inherited from the group.
+
+C<c:[digits]> clones permissions from user with id [digits]
+
+C<C:,[string]> sets the exact permissions indicated by [string].  It is currently up to the caller to ensure 
+that related/cascading permissions are set correctly;  see C<%DNSDB::permchains> for the current set.  Current 
+valid permission identifiers match 
+C<(group|user|domain|record|location|self)_(edit|create|delete|locchg|view)>, however see C<@DNSDB::permtypes> 
+for the exact list.
+
+The comma after the colon is not a typo.
+
+=item fname
+
+First name
+
+=item lname
+
+Last name
+
+=item phone
+
+Phone number
+
+=back
+
+Note that some user properties originate in DNS Administrator's inspiration, VegaDNS.
+
+=cut
 sub addUser {
   my %args = @_;
@@ -355 +601 @@
 #sub checkUser {}
 
+
+=head3 updateUser
+
+Update a user's username, password, state, type, first/last names, and/or phone number
+
+Most arguments are the same as for addUser.
+
+=over 4
+
+=item uid
+
+The ID of the user record
+
+=item username
+
+The username
+
+=item group
+
+The group ID the user is in (for logging).  Users cannot currently be moved to a different group.
+
+=item pass
+
+An updated password, if provided.  Leave blank to keep the existing password.
+
+=item state
+
+The account state (active/inactive).  Takes the same values as addUser.
+
+=item type
+
+The account type (user [C<u>] or superuser [C<S>])
+
+=item fname
+
+First name (optional)
+
+=item lname
+
+Last name (optional)
+
+=item phone
+
+Phone contact (optional)
+
+=back
+
+=cut
 sub updateUser {
   my %args = @_;
@@ -376 +670 @@
 }
 
+
+=head3 delUser
+
+Delete a user
+
+=over 4
+
+=item uid
+
+The ID of the user record to delete
+
+=back
+
+=cut
 sub delUser {
   my %args = @_;
@@ -398 +706 @@
 #sub getLocList {}
 
+
+=head3 getLocDropdown
+
+Retrieve a list of locations for display in a dropdown.
+
+=over 4
+
+=item group
+
+The group ID to select locations from
+
+=item defloc
+
+Optional argument to flag the "default" location in the list
+
+=back
+
+Returns an arrayref to a list of hashrefs with elements C<locname>, C<loc> and C<selected>.  C<selected> will 
+be 0 for all entries unless the C<loc> value matches C<defloc>, where it will be set to 1.
+
+=cut
 sub getLocDropdown {
   my %args = @_;
@@ -408 +737 @@
 }
 
+
+=head3 getSOA
+
+Retrieve the SOA record for a zone
+
+=over 4
+
+=item defrec
+
+Default/live records flag.  Accepts C<y> and C<n>.
+
+=item revrec
+
+Forward/reverse flag.  Accepts C<y> and C<n>.
+
+=item id
+
+The zone ID (if C<defrec> is C<y>) or the group ID (if C<defrec> is C<n>) to retrieve the SOA from
+
+=back
+
+=cut
 sub getSOA {
   my %args = @_;
@@ -428 +779 @@
 #sub updateSOA {}
 
+
+=head3 getRecLine
+
+Retrieve all fields for a specific record
+
+=over 4
+
+=item defrec
+
+Default/live records flag.  Accepts C<y> and C<n>.
+
+=item revrec
+
+Forward/reverse flag.  Accepts C<y> and C<n>.  Mildly abused to determine whether to include C<distance>, 
+C<weight>, and C<port> fields, since MX and SRV records don't make much sense in reverse zones.
+
+=item id
+
+The record ID (if C<defrec> is C<y>) or default record ID (if C<defrec> is C<n>) to retrieve
+
+=back
+
+=cut
 sub getRecLine {
   my %args = @_;
@@ -442 +816 @@
 }
 
+
+=head3 getRecList
+
+Retrieve a list of records for a zone.
+
+=over 4
+
+=item id
+
+The zone ID (if C<defrec> is C<n>) or group ID (if C<defrec> is C<y>) to retrieve records from
+
+=item defrec
+
+Default/live records flag.  Accepts C<y> and C<n>.
+
+=item revrec
+
+Forward/reverse flag.  Accepts C<y> and C<n>.
+
+=back
+
+Optional arguments
+
+=over 4
+
+=item offset
+
+Offset from the start of the raw record list.  Mainly for pagination.  Defaults 0.
+
+=item nrecs
+
+Number of records to return.  Defaults to C<$DNSDB::perpage>
+
+=item sortby
+
+Sort field.  Defaults to host for domain zones, val for reverse zones.  Supports multifield sorts;  pass the 
+fields in order separated by commas.
+
+=item sortorder
+
+SQL sort order.  Defaults to C<ASC>.
+
+=item filter
+
+Return only records whose host or val fields match this string.
+
+=item type, distance, weight, port, ttl, description
+
+If these arguments are present, use the value to filter on that field.
+
+=back
+
+=cut
 sub getRecList {
   my %args = @_;
@@ -486 +913 @@
 }
 
+
+=head3 getRecCount
+
+Return count of non-SOA records in zone (or default records in a group).
+
+Uses the same arguments as getRecList, except for C<offset>, C<nrecs>, C<sortby>, and C<sortorder>.
+
+=cut
 sub getRecCount {
   my %args = @_;
@@ -525 +960 @@
 } # getRecCount()
 
+
+=head3 addRec
+
+Add a record to a zone or add a default record to a group.
+
+Note that the name, type, and address arguments may be modified for normalization or to match available zones 
+for A+PTR and related metatypes.
+
+=over 4
+
+=item defrec
+
+Default/live records flag. Accepts C<y> and C<n>.
+
+=item revrec
+
+Forward/reverse flag. Accepts C<y> and C<n>.
+
+=item parent_id
+
+The ID of the parent zone or group.
+
+=item name
+
+The fully-qualified hostname for the record.  Trailing periods will automatically be stripped for storage, and 
+added on export as needed.  Note that for reverse zone records, this is the nominal record target.
+
+=item type
+
+The record type.  Both the nominal text identifiers and the bare integer types are accepted.
+
+=item address
+
+The record data or target.  Note that for reverse zones this is the nominal .arpa name for the record.
+
+=item ttl
+
+The record TTL.
+
+=item location
+
+The location identifier for the record.
+
+=item expires
+
+Flag to indicate the record will either expire at a certain time or become active at a certain time.
+
+=item stamp
+
+The timestamp a record will expire or become active at.  Note that depending on the DNS system in use this may 
+not result in an exact expiry or activation time.
+
+=back
+
+B<Optional arguments>
+
+=over 4
+
+=item distance
+
+MX and SRV distance or priority
+
+=item weight
+
+SRV weight
+
+=item port
+
+SRV port number
+
+=back
+
+=cut
 # The core sub uses references for some arguments to allow limited modification for
 # normalization or type+zone matching/mapping/availability.
@@ -556 +1064 @@
 } # rpc_addRec
 
+
+=head3 updateRec
+
+Update a record.
+
+Takes the same arguments as C<addRec> except that C<id> is the record to update, not the primary parent zone ID.
+
+If C<stamp> is blank or undefined, any timestamp will be removed.
+
+=cut
 sub rpc_updateRec {
   my %args = @_;
@@ -590 +1108 @@
 
 
+
+=head3 addOrUpdateRevRec
+
+Add or update a reverse DNS record (usually A+PTR template) as appropriate based on a passed CIDR address and 
+hostname pattern.  The record will automatically be downconverted to a PTR template if the forward zone 
+referenced by the hostname pattern is not managed in this DNSAdmin instance.
+
+=over 4
+
+=item cidr
+
+The CIDR address or IP for the record
+
+=item name
+
+The hostname pattern for template records, or the hostname for single IP records
+
+=back
+
+=cut
 # Takes a passed CIDR block and DNS pattern;  adds a new record or updates the record(s) affected
 sub addOrUpdateRevRec {
@@ -685 +1223 @@
 } # done addOrUpdateRevRec()
 
+
+=head3 updateRevSet
+
+Update reverse DNS entries for a set of IP addresses all at once.  Calls addOrUpdateRevRec internally.
+
+=over 4
+
+=item host_[ip.add.re.ss] (Multiple entries)
+
+One or more identifiers for one or more IP addresses to update reverse DNS on.  The value of the argument is the 
+hostname to set on that IP.
+
+=back
+
+=cut
 # Update rDNS on a whole batch of IP addresses.  Presented as a separate sub via RPC
 # since RPC calls can be s...l...o...w....
@@ -715 +1268 @@
 } # done updateRevSet()
 
+
+=head3 splitTemplate
+
+Split a PTR template record into multiple records.
+
+=over 4
+
+=item cidr
+
+The CIDR address for the record to split
+
+=item newmask
+
+The new masklength for the new records.  
+
+=back
+
+=cut
 # Split a template record as per a passed CIDR.
 # Requires the CIDR and the new mask length
@@ -782 +1353 @@
 } # done splitTemplate()
 
+
+=head3 resizeTemplate
+
+Resize a template record based on a pair of passed CIDR addresses.
+
+=over 4
+
+=item oldcidr
+
+The old CIDR to look for in the existing records
+
+=item newcidr
+
+The new CIDR
+
+=back
+
+=cut
 # Resize a template according to an old/new CIDR pair
 # Takes the old cidr in $args{oldcidr} and the new in $args{newcidr}
@@ -850 +1439 @@
 } # done resizeTemplate()
 
+
+=head3 templatesToRecords
+
+Convert one or more template records to individual IP records, expanding the template as would be done on 
+export.
+
+=over 4
+
+=item templates
+
+A list/array of CIDR addresses to search for for conversion.
+
+=back
+
+=cut
 # Convert one or more template records to a set of individual IP records.  Expands the template.
 # Handle the case of nested templates, although the primary caller (IPDB) should not be
@@ -928 +1532 @@
 } # done templatesToRecords()
 
+
+=head3 delRec
+
+Delete a record.
+
+=over 4
+
+=item defrec
+
+Default/live records flag. Accepts C<y> and C<n>.
+
+=item revrec
+
+Forward/reverse flag. Accepts C<y> and C<n>.  Used for logging to pick the "primary" zone of the record.
+
+=item id
+
+The record to delete.
+
+=back
+
+=cut
 sub delRec {
   my %args = @_;
@@ -941 +1567 @@
 }
 
+
+=head3 delByCIDR
+
+Delete a record by CIDR address.
+
+=over 4
+
+=item cidr
+
+The CIDR address for the record or record group to delete.
+
+=back
+
+B<Optional arguments>
+
+=over 4
+
+=item delforward (default 0/off)
+
+Delete the matching A record on A+PTR and similar metarecords.
+
+=item delsubs (default 0/off)
+
+Delete all records within C<cidr>.  Send C<y> if desired, otherwise it reverts to default even for other 
+otherwise "true" values.
+
+=item parpatt
+
+Template pattern to add a replacement record if the delete removes all records from a reverse zone.
+
+=back
+
+=cut
 sub delByCIDR {
   my %args = @_;
@@ -1059 +1718 @@
 } # end delByCIDR()
 
+
+=head3 delRevSet
+
+Delete a set of single-IP records similar to updateRevSet
+
+=over 4
+
+=item cidrlist
+
+Simple comma-separated string containing the IP addresses that should be removed.
+
+=back
+
+=cut
 # Batch-delete a set of reverse entries similar to updateRevSet
 sub delRevSet {
@@ -1077 +1750 @@
 #sub getLogEntries {}
 
+
+=head3 getRevPattern
+
+Get the pattern that would be applied to IPs in a CIDR range that do not have narrower patterns or separate 
+individual reverse entries.
+
+=over 4
+
+=item cidr
+
+The CIDR address range to find a pattern for.
+
+=item group
+
+The group to restrict reverse zone matches to.
+
+=item location
+
+The DNS view/location to restrict record matches to.
+
+=back
+
+=cut
 sub getRevPattern {
   my %args = @_;
@@ -1085 +1781 @@
 }
 
+
+=head3 getRevSet
+
+Retrieve the set of per-IP reverse records within a CIDR range, if any.
+
+Returns a list of hashes.
+
+=over 4
+
+=item cidr
+
+The CIDR address range to find a pattern for.
+
+=item group
+
+The group to restrict reverse zone matches to.
+
+=item location
+
+The DNS view/location to restrict record matches to.
+
+=back
+
+=cut
 sub getRevSet {
   my %args = @_;
@@ -1093 +1813 @@
 }
 
+
+=head3 getTypelist
+
+Retrieve a list of record types suitable for a dropdown form field.  Returns only record types currently 
+supported by DNSAdmin.
+
+Returns a list of hashes.
+
+=over 4
+
+=item recgroup
+
+Flag argument to determine which record types will be returned.  Values not listed fall back to C<f>.
+
+=over 4
+
+=item r
+
+Logical records commonly found in reverse zones (includes A+PTR and related metatypes)
+
+=item l
+
+Records that can actually be looked up in the DNS.
+
+=item f
+
+Logical records commonly found in forward zones (includes A+PTR and similar metatypes that include a forward 
+record component).  Append C<o> to exclude the metatypes.
+
+=back
+
+=item selected
+
+Optional flag argument if a particular type should be "selected".  Sets the C<tselect> key on that entry.  Note 
+that the passed type will always be present in the returned list, even if it wouldn't be otherwise - eg, PTR 
+template if C<recgroup> is set to C<fo>, or SRV if C<recgroup> is set to C<r>.
+
+=back
+
+=cut
 sub getTypelist {
   my %args = @_;
@@ -1102 +1862 @@
 }
 
+
+=head3 getTypemap
+
+Return DNS record type hash mapping DNS integer type values to text names
+
+=cut
 sub getTypemap {
   my %args = @_;
@@ -1108 +1874 @@
 }
 
+
+=head3 getReverse_typemap
+
+Return DNS record type hash mapping text names to integer type values
+
+=cut
 sub getReverse_typemap {
   my %args = @_;
@@ -1117 +1889 @@
 #sub isParent {}
 
+
+=head3 zoneStatus
+
+Get or set the status of a zone.  Returns the status of the zone.
+
+=over 4
+
+=item zoneid
+
+The ID of the zone to get or set status on
+
+=back
+
+B<Optional arguments>
+
+=over 4
+
+=item reverse
+
+Set to C<y> if you want to get/set the status for a reverse zone
+
+=item status
+
+Pass C<0> or C<domoff> to set the zone to inactive;  C<1> or C<domon> to set it to active
+
+=back
+
+=cut
 sub zoneStatus {
   my %args = @_;
@@ -1128 +1928 @@
   my $status = $dnsdb->zoneStatus(@arglist);
 }
+
+
+=head3 getZonesByCIDR
+
+Get a list of reverse zones within a passed CIDR block.  Returns a list of hashes.
+
+=over 4
+
+=item cidr
+
+The CIDR range to look for reverse zones in
+
+=back
+
+=cut
 
 # Get a list of hashes referencing the reverse zone(s) for a passed CIDR block
@@ -1150 +1965 @@
   return \@methods;
 }
+
+
+# and we're done.  close the POD
+
+#back