NameSurfer Suite
Using the NameSurfer Command Line Interface
FusionLayer

NameSurfer 7.6.4.1


Introduction

NameSurfer provides two alternative ways of making changes to DNS data: a forms-based WWW user interface for easy interactive use, and a command line interface (CLI) which is intended primarily for non-interactive use, such as automated updates and integration with existing applications. This document describes the use of the command line interface in detail.

The nsctl program

The NameSurfer command line interface consists of a program called nsctl, usually located in /usr/local/namesurfer/bin/nsctl.

The nsctl program works by contacting the NameSurfer daemon on the local host using a TCP connection, and issuing update requests over that connection. Update requests are cryptographically authenticated, based on a shared secret stored in the file /usr/local/namesurfer/db/secrets. This file is owned by the user namesurf and is not readable by other users (except of course root). Therefore, only the users namesurf and root can make changes to the DNS data using nsctl. The command line interface has no concept of "user accounts" like the WWW user interface does.

Available nsctl commands

The following commands are available :

Updating reverse mappings automatically

The nsctl program does not update reverse mappings by default. If you want automatic reverse updates similar to the ones performed by the WWW user interface, add the global option, --auto-reverse immediately following the nsctl command. This feature can be used with any command that causes changes to DNS data, such as update, xfer, or mf-load. For example,

   nsctl --auto-reverse update --zone demo.net. --add pear A 10.0.0.3
   nsctl --auto-reverse xfer --zone demo.net --ns 10.0.1.2

Managing zone data

Creating a new zone from scratch

A new zone can be created from scratch using the nsctl addzone command. Initial zone data is given using --add arguments just as with the nsctl update command. You must give an SOA record in this way; giving other initial data is optional. In the following example, a SOA record and two NS records are given as initial data for the new zone.

   nsctl zone-add --zone demo.net. \
      --add @ SOA ns1 hostmaster 96041720 10800 3600 1814400 86400  \
      --add @ NS ns1 \
      --add @ NS ns2

Loading an entire zone by zone transfer

An entire zone can be loaded into NameSurfer from another name server by using the nsctl xfer command. This command fetches the zone data by doing a zone transfer from a given name server, and creates an identical zone in NameSurfer. For example:

   nsctl xfer --zone demo.net --ns 10.0.1.2
The nsctl xfer command accepts the following options:
--zone zonename
The name of the zone to transfer. This option is mandatory.

--class class
The name or decimal number of the DNS class. The default is IN (the Internet class).

--ns server
The IP address of the name server to transfer the zone from. A domain name can also be used if the local host has a working resolver.

Loading an entire zone from a master file

An entire zone can be loaded into NameSurfer from a RFC1035 master file by using the nsctl mf-load command. For example:

   nsctl mf-load --zone demo.net --file /etc/namedb/demo.net.db
The nsctl mf-load command accepts the following options:
--zone zonename
The name of the zone to transfer. This option is mandatory.

--class class
The name or decimal number of the DNS class. The default is IN (the Internet class).

--file filename
The name of the master file to load.

Deleting an entire zone

An entire zone can be deleted from NameSurfer by using the nsctl zone-del command. For example:

   nsctl zone-del --zone demo.net.
The nsctl zone-del accepts the following options :
--zone zonename
The name of the zone to delete. This option is mandatory.
--view viewname
The name of the view where zone is in. This option is optional.
--permanent
This option is optional. Using it will erase all information about the zone, including its change log.

Listing all managed zones

All zones (and their corresponding views) managed by NameSurfer can be listed using nsctl zone-list. For example: 
nsctl zone-list
The following options can be used to limit what nsctl zone-list outputs:
--enabled yes / no
Only list enabled (yes) or disabled (no) zones.
--DNSSEC yes / no
Only list zones that have DNSSEC enabled (yes) or disabled (no).
--type pri / sec
Only list either primary (pri) or secondary (sec) zones.
--view view1,view2
List zones in a given view. To list zones from different views in one command, use comma sepated list.
--tag tagname[:tagvalue]
List zones that have tag with tagname tagvalue pair. Note:Use of tagvalue is optional.
--idn yes / no
Select between listing zones that have (yes) IDN name and zone that do not (no) have IDN name.

Listing zone attributes

List all attributes of a zone by using nsctl zone-get. For example:
nsctl zone-get --zone example.com
The nsctl zone-get accepts the following option :
--zone zonename
The name of the zone whose attributes are listed. This option is mandatory.

Modifying zone attributes

Adding, deleting and updating zone attributes is done with nsctl zone-update command. For example : 
  nsctl zone-update --zone example.com --add-param DEFAULT_TTL 86400
  nsctl zone-update --zone example.com --del-param DEFAULT_TTL
  nsctl zone-update --zone example.com --upd-param DEFAULT_TTL 43200
The nsctl zone-update accepts the following options :
--zone zonename
The name of the zone to update. This option is mandatory.
--view viewname
The name of the view where zone is in. This option is optional.
--add-param paramname value
The name and value of the attribute to be added to zone.
--upd-param paramname value
The name of the attribute to update and the new value.
--del-param paramname
The name of the attribute to delete.

Adding and deleting resource records

The most common use of the CLI is to incrementally update the DNS data for one or several names by adding and/or deleting some resource records.

This is accomplished by the nsctl update command. Here are some examples of nsctl update commands:

   nsctl update --zone demo.net. --add banana A 10.0.0.1

   nsctl update --zone demo.net. --delete apple A 10.0.0.2

   nsctl update --zone demo.net. \
      --add orange MX 10 mailhub \
      --add orange MX 20 mail.isp.net.
The nsctl update command is followed by options beginning with a double dash (--):

--zone zonename
The name of the DNS zone to update. This option is mandatory. All the records that are added or deleted in a single invocation of nsctl update must belong to the same zone.

--class class
The name or decimal number of the DNS class. The default is IN (the Internet class).

After the options, the actual additions and deletions of resource records are specified as groups of argument words beginning with --add or --delete. The words following the --add or --delete are interpreted as a name and a resource record, using a syntax similar to that of a single entry in an RFC1035 master file. That is, they can take either of the following forms:

    <domain-name> [<TTL>] [<class>] <type> <RDATA>
    <domain-name> [<class>] [<TTL>] <type> <RDATA>
Domain names with no trailing period are interpreted relative to the zone root given with the --zone option. Note that this way of interpreting a domain name that has no periods is similar to that of BIND, but different from that of the WWW user interface.

If the TTL is omitted, the SOA MINIMUM value is used.

Manipulating user accounts

Listing user accounts

Listing all user accounts in the system with command nsctl user-list. For example:
nsctl user-list
The command has no options.

Adding a user account

Adding new users to NameSurfer is done with nsctl user-add. Here is an example of how to create user account called einar, with the password SalaSana : 
nsctl user-add --user einar --password aB4nZtU5fBQB6
The nsctl user-add accepts the following options :
--user username
The user account to create. This option is mandatory.
--password password
The encrypted password. This option is mandatory.

The encrypted passwords may be produced using existing software, such as the htpasswd program used with many WWW servers. If you don't have an existing in-house procedure for password encryption, the following short Perl script may be useful. It will read plaintext passwords from standard input, encrypt them, and print the encrypted passwords on standard output.

    #!/usr/local/bin/perl5
    sub salt {
        substr("./" . join("", "0".."9","A".."Z","a".."z"), int rand 64)
    }
    srand time;
    while (<>) {
        chomp; print crypt($_, salt.salt), "\n";
    }

Updating a user accounts

nsctl user-update Enabling previously created user account : 
nsctl user-update --user einar --add-param U_STATUS enabled
--user username
User account to update. This option is mandatory.
--add-param param name param value
Parameter name to add and its value. This option is optional
--del-param param name
Parameter name to remove. This option is optional.
Multiple --add-param and --del-param options can be given at the same time.

Listing user attributes

nsctl user-get 
nsctl user-get --user einar
--user username
User account whose attributes will be displayed. This option is mandatory.

Deleting a user account

nsctl user-del 
nsctl user-del --user einar
--user username
User account to be deleted. This option is mandatory.

Manipulating groups

Listing all groups

Listing all groups in NameSurfer is done with command nsctl group-list. For example : 
nsctl group-list
The command has no options.

Adding a new group

Adding a new group to NameSurfer is done with nsctl group-add command.
For example, creating a group named example and adding demouser to newly created group : 
nsctl group-add --group example --description "Example group"
nsctl group-update --group example --add-param G_STATUS enabled --assign demouser
--group groupname
Name of the group to add. This option is mandatory.
--description description
Optional description of the group. If description contains spaces, surround it with quotation marks.

Deleting a group

nsctl group-del Deleting a group from NameSurfer is done with command nsctl group-del command. For example : 
nsctl group-del --group example
--group groupname
Name of the group to delete. This option is mandatory.

List group attributes

Listing all attributes for a group is done with command nsctl group-get. For example : 
nsctl group-get --group example
--group groupname
Name of the group to get. This option is mandatory.

Updating a group

Updating group parameters is done with command nsctl group-update. For example : 
nsctl group-update --group example --assign demouser --add-param G_STATUS enabled
Note: to update a group parameter, you need to use both --del-param and --add-param.
--group groupname
Name of the group to update. This option is mandatory.
--add-param param name param value
Parameter name and value to add to group
--del-param param name
Parameter to remove from group
--assign username
Username to add to group
--unassign username
Username to remove from group

Group attributes

Group attributes are displayed with group-get command and can be manipulated with group-update command. The most useful attributes are :
G_STATUS
Group is active when this is set to enabled. To disable the group, set value to disabled
SUPERUSER
Switch to determine, whether group has superuser rights.

Manipulating views

Listing views

Listing all views configured into NameSurfer is done with the command view-list. For example : 
nsctl view-list
The command has no options.

Manipulating remote secondary servers

Print configuration

This command prints the configuration of a configured remote secondary, either dhcp or bind. Filename is always dhcpd.conf or named.conf, server is same as configured in WebUI. For example: 
        nsctl secondary-print --file named.conf --server ns2.demo.net > ns2.named.conf
Prints out named.conf of ns2.demo.net to ns2.named.conf.
--file filename
Either named.conf or dhcpd.conf (Mandatory)
--server servername
Name of the remote secondary (Mandatory)

If the server is not of a managed type, output of this command will be empty.

Adding remote secondary

This command reads the configuration file specified and installs it to the NameSurfer Remote Secondary configuration database for the server specified. The file name may contain the full or a relative path to the file. This path part of the file name does not go to the database. The file name should be either named.conf or dhcpd.conf. For example: 
nsctl secondary-add --file named.conf --type managed_named --server ns2.demo.net --set "ssh_remote_user=namesurf"
This adds a new Remote Secondary Server to NameSurfer and a initial configuration for it. Configuration can be edited afterwards from WebUI.
--file filename
Either named.conf or dhcpd.conf (Mandatory)
--type servertype
Type of the remote secondary. Must be one of standalone_named, legacy, managed_named, SNS, standalone_dhcpd or managed_dhcpd. (Mandatory>
--server servername
Name of the remote secondary (Mandatory)

Contents of the configuration file are only meaningful for the managed server types.
To set the remote user name for SSH connections correctly, the ssh_remote_user attribute must be set like shown on the example line, otherwise the value will be automatically set to the username of the current local user, which is likely to be incorrect.

Removing a remote secondary

Removing a remote secondary server is done with command secondary-remove. For example : 
nsctl secondary-remove --file named.conf --server ns2.demo.net
Removes the remote secondary ns2.demo.net from the system.
--file filename
Either named.conf or dhcpd.conf (Mandatory)
--server servername
Name of the remote secondary (Mandatory)

Checking the remote secondary configuration

Checking the configuration for a managed secondary server is done with command secondary-check. For example : 
nsctl secondary-check --file named.conf --server ns2.demo.net
will check the named.conf of ns2.demo.net if it exists in the local database.
--file filename
Either named.conf or dhcpd.conf (Mandatory)
--server servername
Name of the remote secondary (Mandatory)

The command returns an error code if checking of a non-managed server is attempted or if the configuration is faulty. In case of faulty configuration, output of the check command that was run is also printed to standard error output.
If everything is OK, the output of the command will be empty and a zero result code will be returned.

Uploading configuration to remote secondary

Uploading the configuration to a remote secondary is done with the command secondary-upload. For example : 
nsctl secondary-upload --file named.conf --server ns2.demo.net
Will upload the named.conf file from local database to the server ns2.demo.net
--file filename
Either named.conf or dhcpd.conf (Mandatory)
--server servername
Name of the remote secondary (Mandatory)

If the secondary server is not managed by NameSurfer or if the upload fails, an error code will be returned.

Process control of the remote secondary server

Secondary server process control is done with commands secondary-start, secondary-stop and secondary-reload. Examples : 
start:
       nsctl secondary-start --file named.conf --server ns2.demo.net

stop:
       nsctl secondary-stop --file named.conf --server ns2.demo.net

reload:
       nsctl secondary-reload --file named.conf --server ns2.demo.net
--file filename
Either named.conf or dhcpd.conf (Mandatory)
--server servername
Name of the remote secondary (Mandatory)