B

3DNS Controller Utilities and Scripts

Utilities

The 3DNS Controller includes several utilities and scripts. These utilities and scripts allow you to configure the DNS, and the various features of the 3DNS Controller.

3dparse

The 3dparse utility parses and verifies the syntax of the 3DNS configuration file (wideip.conf). You can use it to verify syntax after making any changes to wideip.conf, before running named.

The 3dparse utility can be used to validate configuration syntax. 3dparse checks global value ranges and to ensure each virtual server is configured on a BIG/ip Controller or other host machine. The 3dparse utility also checks dependencies. For example, TTL values (like bigip_ttl) must be greater than their corresponding timer values (like timer_get_bigip_data).

Use the following syntax with 3dparse:

3dparse [-help] [-v] [-o] [-if <string>] [-of <string>] \
[-sf <string>] [-trim] [-flat] [-actions] [-d] [-s] [-vl] \
[-picky]

The options for 3dparse are:

-help

Displays the list of available options.

-v

Displays the version information.

-o

Writes the configuration information to the output file.

-if <string>

Specifies a file name for the input file. If you do not use this option, 3dparse uses the default input file, /etc/wideip.conf.

-of <string>

Specifies a file name for the output file and writes the configuration information to that file. The default file name is ./3dparse.out.

-sf <string>

Specifies the path for output status file. The default is stdout.

-trim

Writes all path and local DNS information to include files. By default, path and local DNS information is sent to include files.

-flat

Writes all information to one output file, regardless of whether include files are used.

-actions

Writes all actions (production rules) to the output file. By default, production rules are not written to the output file.

-d

Simulates a SIGINT, which has the effect of writing status files to /var/run.

-s

Simulates receiver behavior when loading.

-vl

Turns on syslog verbosity and path loading.

-picky

Specifies that any validation errors are not automatically corrected.

Example of a 3dparse command

The following example shows a 3dparse command. The bold typeface indicates the typed command.

bighost:~# 3dparse -o

3dparse: Initializing ...

3dparse: Parsing /etc/wideip.conf

3dparse: Dumping ./3dparse.out

3dparse: SUCCESS

sod-named

Use the sod-named utility to ensure that a version of named is always running on the 3DNS Controller. Always run sod-named after rebooting the 3DNS Controller.

If sod-named is running, do not manually start named, as this causes the currently running named process to stop.

sod-named performs the following functions:

• Starts and watches new named and syncd processes if named and syncd are not running when sod-named is started.
• Monitors any running named and syncd processes.
• Starts new named and syncd processes if the watched named and syncd processes stop.
• Keeps secure any dumped named core files by renaming the core file and adding a timestamp suffix. sod-named then compresses the core file.
• Presents an error message if you attempt to start more than one sod-named process.
• Logs an emergency message if the named process runs for less than one hour before stopping, ten times in a row; this behavior usually indicates a serious problem with named. You can use the -restart or -seconds arguments when you start sod-named to change the time parameters. These arguments are described later in this section.
• Parses named.conf to find the directory command in order to find in which directory to run and where to dump and find named cores. If more than one directory command is found in named.conf, sod-named uses the last one it finds.

  If you are using a ps command followed by a grep named command to find all named process on a 3DNS Controller, add the -ww argument to the ps command. This causes ps to print out long lines, ensuring that sod-named appears in the output.

  A 3DNS Controller does not have to use sod-named. You can instead use named and ndc. See named , on page B-5, and Configuring syslog for 3DNS messages , on page B-7.

  Use the following syntax with sod-named:

sod [ -tty00 ] [ -tty01 ] [ -ethernet ]
[ -force_master ] [ -force_slave ] [ -force_active ]
[ -force_standby ] [ -restart # of restarts ]
[ -seconds # of secs ] [ -config named.conf path ]
[ -no-watch-named ] [ -no-watch-syncd ]
[ -shared IP address ] [ -peer IP address ]

3ndc

3ndc allows the name server administrator to send various signals to the name server, or to restart it.

Note: The name daemon control interface command ndc is now an alias for 3ndc.

The syntax for 3ndc is as follows:

3ndc directive [ ...]

When you use 3ndc, you can specify directives. Directives are not required. Directives for 3ndc include:

status

Display the current status of named, sod_named, and syncd as shown by ps(1).

dumpdb

Write named's database and cache to /var/tmp/named_dump.db. It uses the INT signal.

reload

Checks the serial numbers of all primary and secondary zones and reloads those that have changed. Uses the HUP signal.

stats

Writes statistics to /var/tmp/named.stats. Uses the IOT or ABRT signal.

trace

Increments the tracing level by one. Whenever the tracing level is not zero, trace information is written to /var/tmp/named.run. Higher tracing levels result in more detailed information. Uses the USR1 signal.

notrace | cmd

Rereads the /var/run/widip.cmd file and sets its tracing level to zero. The /var/tmp/named.run closes if it is open. Uses the USR2 signal. Using notrace or cmd has the same effect, and can be used in addition to using the same argument with ndc.

querylog

Toggles the query logging feature which, while on, results in a syslog(3) entry for each incoming query. It uses the WINCH signal. Note that query logging consumes log file space. This directive may also be given as qrylog.

start

Starts sod-named, if it is not running. sod-named starts named and syncd. If named and syncd processes are already running, sod-named starts and watches the current named and syncd processes.

stop

Stops sod-named, named, and syncd, if they are running.

restart

Stops and restarts sod-named, named, and syncd.

named

named is the Internet domain name server. If no arguments are specified, named opens the default boot file (/etc/named.conf), reads any initial data, and listens for queries.

named uses the following syntax:

named [ -(b|c) <config_file> ] [ -d <debuglevel>] [ -f ] \
[ -g <group_name> ] [ -p <port#> ] [ -q ] [ -r ] \
[ -t <directory> ] [ -u <user_name> ] [ -v ] [ -w <directory> ]\ [ config_file ]

The options for named include:

-b

Specifies an alternate boot file. This argument is overridden by any configuration file which is specified at the end of the command line. The default value is /etc/named.conf.

-d

Prints debugging information. The number specified after this option determines the level of printed messages.

-f

Runs the process in the foreground.

-g

Specifies which group the server should run as after it initializes. You can specify a group name or a numeric group ID.

-p

Use the specified remote port number; this is the port number to which named sends queries. The default value is the standard port number as returned by the getservby-name command for the service domain. In earlier versions of named, the syntax
-p port#[/localport#] was supported. The first port was used when contacting remote servers, and the second one was the service port bound by the local instance of named. The current usage is equivalent to the old usage without the localport# specified; this functionality can be specified with the listen-on clause of the configuration file's options statement.

-q

Traces all incoming queries if named was compiled with the QRYLOG defined command. Note that this option is deprecated in favor of the boot file directive: options query-log.

-r

Turns off recursion on the server. Answers can come only from local (primary or secondary) zones. This option can be used on root servers. Note that this option is deprecated in favor of the boot file directive: options no-recursion.

-t

Specifies the directory the server should chroot(2) into as soon as it finishes processing command line arguments.

-u

Specifies the user the server should run as after it initializes. You can specify a user name or a numeric user ID. If you did not use the -g option, the group ID used is the primary group of the specified user--initgroups(3)--is called, so all of the user's groups are available to the server.

-v

Displays the version information.

-w

Sets the working directory of the server. The directory clause of the configuration file's options statement overrides any value specified on the command line. The default working directory is the current directory.

[config_file]

Any additional argument is taken as the name of the configuration file, for compatibility with older implementations; as noted above, this argument overrides any configuration file specified by the -b and -c options. If no further argument is given, the default configuration file is used (/etc/named.conf).

For more information on named, see the named man page.

Configuring syslog for 3DNS messages

Although the syslog daemon is configured to save 3DNS Controller messages by default, the information in this section is provided in case you ever need to reconfigure your system. The lines listed in the following procedure are default entries for files shipped with a new 3DNS Controller.

Both the big3d agent and named utility use the syslog daemon and all messages are written to the local2 facility.

You can view the log files in the F5 Configuration utility by clicking Log Files in the navigation pane.

To set up 3DNS Controller logging manually

1. Add the following lines to the /etc/syslog.conf file.

local2.err /var/log/3dns local6.err /var/log/sync

To include warnings in normal operations, also add the following line:

local2.warning /var/log/3dns

For full debugging, add the following line:

local2.debug /var/log/3dns

The above lines are somewhat equivalent to:

local2.* /var/log/3dns

As an alternative, you can use a different file to capture a session without affecting the default files. For example, you could use a line like the following:

local2.debug /var/log/3dns.debug

To switch logging levels or specify another file name, edit the /etc/syslog.conf file and restart syslogd or issue it a SIGHUP.

1. Create an empty 3DNS Controller file in /var/log by typing the following on the command line:

% touch 3dns
% touch sync

Note that in the above example, 3dns is the name of the file you are creating. You can use this command to create other files for the 3DNS Controller (with different names). You need only create other 3DNS Controller files when solving configuration problems.

You must touch each file that you create. Continuing with the examples in step 1, type the following entry:

% touch 3dns.debug

1. Restart syslog by typing the following on the command line:

kill -HUP `cat /var/run/syslog.pid`

Log rotation

The 3DNS Controller's log file is called /var/log/3dns. The 3DNS Controller uses log rotation to keep log files from becoming overly large. A script included with the 3DNS Controller, /etc/daily, automatically runs each night, compressing the existing information in the log file. We do not recommend that you edit this file.

syslog.conf

The syslog.conf file is the configuration file for the syslogd program. It consists of blocks of lines separated by program specifications, with each line containing two fields:

• Selector field
  Specifies the types of messages and priorities to which the line applies.
• Action field
  Specifies the action to be taken if syslogd receives a message that matches the selection criteria.

  The selector field is separated from the action field by one or more space or tab characters.

  The Selector function is encoded as a facility, a period (.), and a level, with no intervening white space. Both the facility and the level are not case-sensitive.

  The facility describes the part of the system generating the message, and is one of the following keywords: auth, authpriv, cron, daemon, ftp, kern, lpr, mail, mark, news, ntp, syslog, user, uucp, and local0 through local7. These keywords (with the exception of mark) correspond to the similar LOG_ values specified to the openlog and syslog library routines.

  The level describes the severity of the message. The severity levels include (from highest to lowest): emerg, alert, crit, err, warning, notice, info, and debug. These correspond to the similar LOG_ values specified to the syslog library routine.

  Each block of lines in the syslog.conf file is separated from the previous block by a tag. The tag is a line beginning with one of the following:

• #!prog
  Used for compatibility with the previous syslogd; for example, if one is sharing syslog.conf files.
• !prog
  Each block will be associated with calls to syslog from that specific program.

  The action specified in the action field is taken if a message received matches the specified facility and is of the specified level (or a higher level), and if the first word in the message after the date matches the program.

  To specify multiple selectors for a single action, separate each selector with a semicolon (;) character. It is important to note that each selector can modify the ones preceding it.

  To specify multiple facilities for a single level, separate each selector with a comma (,) character.

  An asterisk (*) can be used as a wildcard character to specify all facilities, all levels, or all programs.

  The special facility mark receives a message at info priority every 20 minutes. This is not enabled by a facility field. The facility command uses the following marks:

• A comma separated list of users
  Selected messages are written to those users if they are logged in.
• An asterisk
  Selected messages are written to all logged-in users.
• A vertical bar (|)
  The vertical bar is followed by a command to which to pipe the selected messages. The command is passed to a /bin/sh for evaluation, so usual shell metacharacters or input/output redirection can occur. (However, note that redirecting stdio buffered output from the invoked command can cause additional delays, or even lost output data in case a logging sub-process exited with a signal.) The command itself runs with stdout and stderr redirected to /dev/null. Upon receipt of a SIGHUP, syslog.conf closes the pipe to the process. If the process did not exit voluntarily, it will be sent a SIGTERM signal after a grace period of up to 60 seconds.
  
  The command starts only when the data that should be piped to it arrives. If the process exits later, it restarts as necessary. If you want the sub-process to get exactly one line of input only (which can be very resource-consuming if there are a lot of messages flowing quickly), you can do this by exiting after just one line of input. If necessary, a script wrapper can be written to this effect.
  
  Unless the command is a full pipeline, you probably want to start the command with exec so that the invoking shell process does not wait for the command to complete.

Warning: The process is started under the UID that invokes syslogd, usually the superuser.

Blank lines and lines whose first non-blank character is a hash (#) character are considered to be comments, and are ignored.

Example

The following is an example of a configuration file:

# Log all kernel messages, authentication messages of

# level notice or higher and anything of level err or

# higher to the console.

# Don't log private authentication messages!

*.err;kern.*;auth.notice;authpriv.none /dev/console

# Log anything (except mail) of level info or higher.

# Don't log private authentication messages!

*.info;mail.none;authpriv.none /var/log/messages

# The authpriv file has restricted access.

authpriv.* /var/log/secure

# Log all the mail messages in one place.

mail.* /var/log/maillog

# Everybody gets emergency messages, plus log them on another

# Save ftpd transactions along with mail and news

!ftpd

*.* /var/log/spoolerr

syslogd

The syslogd daemon reads and logs messages to the system console, log files, other machines, and/or users as specified by its configuration file.

The syslogd daemon uses the following syntax:

syslogd [-a <allowed_peer>] [-d] [-f] [-m] [-p] [-s]

Options include the following:

-a <allowed_peer>

Allows allowed_peer to log to this syslogd using UDP datagrams. Multiple -a options may be specified.

Allowed_peer can be any of the following:

• ipaddr/masklen[:service]
  Accepts datagrams from ipaddr (in the usual dotted quad notation) with masklen bits being taken into account when doing the address comparison. If specified, service is the name or number of a UDP service to which the source packet must belong. A service of * allows packets sent from any UDP port. The default service is "syslog". A missing masklen is substituted by the historic class A or class B netmasks if ipaddr belongs to the address range of class A or B, respectively, or by 24 otherwise.
• domainname[:service]
  Accepts datagrams where the reverse address lookup yields the domainname for the sender's address. The meaning of service is described above.
• *domainname[:service]
  Same as above, except that any source host whose name ends in domainname will get permission.

-d

Puts syslogd into debugging mode. This is useful for troubleshooting.

-f

Specifies the path name of an alternate configuration file; the default is /etc/syslog.conf.

-m

Selects the number of minutes between mark messages; the default is 20 minutes.

-p

Specifies the path name of an alternate log socket; the default is /var/run/log.

-s

Operates in secure mode. Does not listen for log message from remote machines.

log2mail

The log2mail program gathers system log messages from the syslogd daemon and mails a copy to each specified address. It is intended to be invoked by syslogd using the "|" construct in the /etc/syslog.conf file, as in the following example:

*.err,auth.notice |/usr/sbin/log2mail root@remote.site.com

The log2mail program begins each mail message with a line of context taken from the previous mail message. The context clarifies the meaning of the "last message repeated n times" messages that are generated by syslogd itself.

log2mail uses this syntax:

log2mail [-t <inverval> ]

One option is available:

-t <interval>

Specifies the minimum interval in seconds between consecutive mail messages. When log2mail receives a new log message, it checks whether <interval> seconds have passed since the last time it mailed a message. If at least that amount of time has passed, log2mail mails the new message without delay. Otherwise, it saves incoming messages and sends them later, after <interval> seconds have passed since the previous mail. This prevents a large number of log messages from producing many mail messages.

The default interval is 300 seconds (5 minutes).

big3d

The big3d utility is the 3DNS daemon which answers metrics collection questions for 3DNS.

Use the following syntax with big3d

big3d [ -foreground ] [ -help ] [ -rxbufsize value ] [ -rtt- timeout value ] [ -txbufsize value ] [ -version ] [ -v ] [ -keyfile file ] [ -encryption_only ] [ -max_active_probers value ] [ -max_active_scanners value ] [ -max_active_hops value ] [ -max_active_snmp value ] [ -loglevel value ]

The options for big3d are:

-foreground

Runs the process in the foreground rather than as a daemon.

-help

Prints this message.

-rxbufsize value

Represents the size of the receive socket buffer. 30720 is the default.

-rtt-timeout value

Overrides timeout value for round trip times.

-txbufsize value

Represents the size of the receive socket buffer. 20480 is the default.

-version

Prints the version information.

-keyfile file

Uses an alternative encryption key file (domestic version only).

<-encryption_only>

Accepts only encrypted messages (domestic version only).

-max_active_probers value -max_active_scanners value -max_active_hops value -max_active_snmp value

Defines the maximum number of factories that can be operating when the controller is in the ACTIVE state.

-loglevel value

Sets the level of messages sent to syslog; notify is the default.

-item

Example

bighost:~# big3d

Files

/var/log/3dns

bigdb

The BIG/db database contains configuration data used by various utilities and daemons that run on a BIG/ip Controller. The database is located at /var/f5/bigdb/user.db. Records are stored in the database as binary data in key/value pairs. You can access the database by using the bigdba command line utility. BIG/config also uses the database to access certain configuration information.

BIG/db keys

• A BIG/db key is a simple character string.
• Key names are not case sensitive.
• Key names may not contain the characters '"', '=', '*', '{' or '}'
• Key names may contain spaces, tabs or newline characters provided the name is always enclosed in '"'s when it is referenced.
• Key names may begin with any valid character, and may be up to 1024 bytes in length.
• In BIG/db a key is composed of one or more subkeys delimited by '.' characters. An example of a valid subkey is BigIp.Test.IpAddr where the top level key is BigIp with a subkey named Test and a subkey IpAddr under Test.

BIG/db records

BIG/db records may be of arbitrary length within the constraint of available memory; however, bigdba imposes a limit of approximately 16KB on the size of a record. Records are typically in the form of character strings, making the data easy to display and modify.

BIG/db dump files

A BIG/db dump file is a simple text file. Text files may be used to keep backup copies of the database and to load new data into the database. You can use the bigdba utility to dump the database to a text file and to load records into the database from a text file.

A line in the text file may be either an assignment, a comment, or an empty key specification.

An assignment has the form

<key>[.subkey[.subkey[...]]] =<value>

A comment begins with a '#' at the beginning of a line, and ends at the next line that does not begin with a '#'. A comment precedes the key that the comment describes.

An empty key is specified by a line containing only the name of the key with no assignment.

It is a good idea to keep a copy of the database in text file format in case the database is accidentally modified.

BIG/db comments

A key ending with the character sequence '.#' is a comment. Any key in the database may have an associated comment record. The key name for a comment is <original key>.#' Comments may contain multiple lines of text describing the purpose of the associated key. By default comments are not displayed by the bigdba utility. Comments are always loaded/dumped with data to and from text files when using the bigdba load and dump commands.

Files

/var/f5/bigdb/user.db /var/f5/bigdb/default.txt

bigdba

The bigdba is a command line interface for configuring the BIG/store database. It allows you to interactively display and modify records in the BIG/store database from the command line. You can also use bigdba to dump the database to a text file and to load the database from a text file.

Use the following syntax for bigdba:

bigdba [-d <dump filename> ] [ -l <loadfilename> ] [ -h | -help ] <database name>

The options for bigdba are:

-d filename

Dumps the entire database to the text file filename and exits.

-l filename

Loads the database from the text file filename and exits. This is an update operation. Any records in the database having the same keys as those in the file are overwritten. Any records in the database which do not have corresponding keys in the file are left unchanged.

-h | -help

Print options.

Interactive Commands

When given no options, bigdba opens the given database for writing, displays a >prompt, and waits for input on the command line. The database is created if it did not previously exist. Valid commands are:

print name[*] | p name[*]

Displays the value stored under the key name. If * is used, the values stored under all keys that begin with name are displayed. Key names are not case sensitive.

name = value

Stores value under the key name. If a value was previously stored under key name, it is overwritten.

d name[*]

Deletes the record stored under the key name. If * is used, delete the values stored under all keys that begin with name. If delete confirmation is on, a confirmation prompt is displayed prior to the deletion of each record.

subkey name | sk name

Adds subkey name to the current key level. Analogous to changing to a subdirectory using the cd command. The current subkey is prepended to the key argument of subsequent commands.

up | up name

Backs up one subkey, or if name is used, backs up through subkey name. Analogous to cd .

set confirm [on|off]

Modifies delete confirmation behavior. When delete confirmation is on, user confirmation is obtained prior to deleting each record given in a delete command. Delete confirmation is on by default.

set comments [on|off]

Modifies comment display. When comment display is on, comment records are displayed by the print command. Comment display is off by default.

dump file

Dumps the entire database to a text file.

load file

Loads the database from a text file. The database is not truncated by a load. Existing records in the database are updated by matching key values in the file.

quit | q | EOF

Exits the bigdba program.

help | ?

Displays help text.

Examples of a bigdba command

For example, to create, display, and delete a record called Bigip.Tests.TestIpAddr in the database /var/f5/bigdb/user.db:
bighost:~# bigdba /var/f5/bigdb/user.db Database "/var/f5/bigdb/user.db" opened. > Bigip.Tests.TestIpAddr = 1.2.3.4 > p Bigip.Tests.TestIpAddr Bigip.Tests.TestIpAddr = "1.2.3.4" > d Bigip.Tests.TestIpAddr Confirm: Delete record for "Bigip.Tests.TestIpAddr" ? [Y] > q bighost:~#

Files

/var/f5/bigdb/user.db /var/f5/bigdb/default.txt

Notes

We recommend that you keep a backup database or text file in case the database is modified by accident.

bind2namesurfer

The bind2namesurfer program loads all master zone files in /etc/named.conf into NameSurfer.

You must have previously configured NameSurfer, and it must be running. If named.conf file to write is not specified, named.conf file to parse is used instead.

Use the following syntax with bind2namesurfer:

bind2namesurfer named.conf file to parse IP address of NameSurfer NameSurfer port# [named.conf file to write ]

Caveats

You should run this program only after you have configured NameSurfer. If you have not yet configured NameSurfer, run config_namesurfer. Refer to the NameSurfer documentation for errors reported when attempting to import zone files using the nsctl utility. This program is located in the directory /var/f5/namesurfer/aux and is not in the default path.

checktrap

The checktrap.pl utility sends traps from syslogd information. It reads from standard input and sends an SNMP trap when a line matches a regular expression. The specific trap sent depends on the regular expression matched. The regular expressions to trap mappings are defined in a file, which is by default /etc/snmptrap.conf.

The checktrap.pl utility is specifically designed to deal with input from syslogd. Normally the user puts calls to checktrap.pl in the /etc/syslogd.conf file.

The checktrap utility uses the following syntax:

checktrap.pl [options]

Syntax of snmptrap.conf file

Comments lines begin with #. All other lines are assumed to be valid for configuration lines. Valid configuration lines are of the following form:

OID REGULAR EXPRESSION DESCRIPTION

The three fields are separated by tabs.

• OID is an SNMP Object Identifier.
• REGULAR EXPRESSION is a Perl Regular Expression.
• DESCRIPTION is a string used in the description field of the trap itself.

The options for checktrap are:

--snmpd_conf_file= filename

The snmpd configuration file. This has the trapsink -- where traps are sent to -- and the trap community string. The default is /etc/snmpd.conf.

--trapd_conf_file= filename

The trap configuration file. It contains the Regular expression to Trap OID mappings. It is explained in the following section Syntax of snmptrap.conf file below. It defaults to /etc/snmptrap.conf.

--trap_program= program

This program actually launches the trap. It should be the snmptrap program provided with the ucd-snmp agent. It defaults to /sbin/snmptrap. This option is for debugging purposes.

Example

To send out an Unknown Error trap when a syslog line begins with Error or error, use the following line:

.1.3.6.1.4.1.3375.1.1.110.2.1 (^[Ee]rror) Unknown Error

Files

/etc/snmptrap.conf

/etc/syslogd.conf

/etc/snmpd.conf

config_httpd

The config_httpd tool is a curses-based configuration tool for the standard webserver. It requires fully-qualified domain names for both the internal and external interfaces by which the webserver will be known. It requires the user name and password for an administrative user, and asks if Support should be given access to the system.

If a user by that name already exists, it will request confirmation that you wish to change that user's password.

The config_httpd tool will then write the webserver configuration and authorization files.

Use the following syntax with config_httpd:

config_httpd

Caveats

Re-running the config_httpd tool again and changing the name of the administrative user will result in the prior user's access to the Configuration utility being dropped to read-only status.

config_httpsd

The config_httpsd tool is a curses-based configuration tool for the secure webserver. It requires fully-qualified domain names for both the internal and external interfaces by which the webserver will be known. It requires information to make a self-signed certificate for the webserver. It also requires the user name and password for an administrative user, and asks if Support should be given access to the system.

If a user by that name already exists, it requests confirmation that you wish to change that user's password.

The config_httpsd tool then writes the webserver configuration file and runs the SSL key generation facilities. This may take a minute or more on an average system.

Use the following syntax with config_httpsd:

config_httpsd

Caveats

Re-running the config_httpsd tool again and changing the name of the administrative user will result in the prior user's access to the Configuration utility being dropped to read-only status.

config_namesurfer

The config_namesurfer tool is a curses-based configuration tool for NameSurfer. It requires fully-qualified domain names that are known by the NameSurfer webserver. It also requires the user name and password for an administrative user.

The config_namesurfer tool initializes the NameSurfer databases and optionally calls bind2namesurfer to load master zone files listed in /etc/named.conf from BIND into NameSurfer, converts /etc/named.conf to use the new NameSurfer zone files, and writes the output of bind2namesurfer to /var/3dns/etc/bind2namesurfer.log.

Use the following syntax with config_namesurfer:

config_namesurfer

Caveats

You should run this program only once, as it attempts to initial the NameSurfer binary database files. However, running it multiple times has no effect.

config_rshd

The config_rshd tool is a curses-based configuration tool for the rsh (remote shell) server. It requests a configuration address from which administrators may access the server. The address may contain wildcards. It also asks if the address for support may be included in the list of permitted hosts. If inetd is not currently configured, configure inetd for the requested services. If the service port for rsh is closed, it opens the service port to permit external access via rsh.

Use the following syntax with config_rshd:

config_rshd

Caveats

Re-running the config_rshd tool again and saying no will not result in rsh being deactivated. Also, administration addresses are appended, not replaced, with each re-run of config_rshd.

config_sshd

The config_sshd tool (configure ssh for BIG/ip) is a curses-based configuration tool for the ssh (secure shell) server. It requests a configuration address from which administrators may access the server via ssh. The address may contain wildcards. It also asks if the address for support may be included in the list of permitted hosts. If the service port for ssh is closed, it opens the service port to permit external access via ssh.

Use the following syntax with config_sshd:

config_sshd

Caveats

Re-running config_sshd again and saying no will not result in ssh being deactivated. Also, administration addresses are appended, not replaced, with each re-run of config_ssh.

syncd

The syncd daemon will synchronize a set of files between the 3DNS Controllers in its sync group. A syncd process is run independently on each controller and each syncd is responsible for detecting the modification of a local file and sending it to the remote syncds as well as receiving newly updated files from remote syncds.

The controllers in a sync group are defined by the sync_group statement in the wideip.conf file. The order of the controllers in the sync group in the wideip.conf file determine the priority of the controllers to see which controller is a Principal or Receiver, but for syncd the order does not matter. Every controller in a sync group is a peer of each other.

Syncd's configuration files that list the files synchronized by syncd are listed in the files sync_list , sync_list.mandatory and sync_list.named (all in the directory /var/3dns/etc ).

The files listed to be synchronized can be plain files, links (syncd will synchronize both the link and the actual file it points to), and directories (the directory and its contents, including sub-directories, will be synchronized). If a file in a synchronized directory is deleted, the deletion will be synchronized and the file will be removed from the same directory on all controllers.

The following files and directories are not allowed to be synchronized: / , /usr, /etc, /var (individual files or directories under those directories can be synchronized), and also the file /etc/netstart. Any file with the following suffixes will also never be synchronized: .core , .core.gz , .bak , .no_sync.

The files to synchronize are listed one per line in one the following sync_list files: sync_list, sync_list.mandatory and sync_list.named (all in the directory /var/3dns/etc). Each file may have one of the following tokens listed in front of the file name:

backup -

Each new version of this file is backed up whether changed locally or remotely. Directories are not backed up, but the files in the directory are backed up. Links are not backed up, but the file to which the link points is backed up. The backups are stored in the directory /var/3dns/staging/backup.

ckpoint -

The file will be checkpointed if syncd is requested to checkpoint its files (by default, any file with backup will be checkpointed). See the section ahead, titled Checkpointing.

fixed -

Once the file's syncd configuration is read in from a sync list, it cannot change, even if the sync list is reread in.

once -

The action associated with this file will be run only once, the first time the file is synchronized to the controller. See the following section, titled Actions.

no_sync -

The file will be watched, but never synchronized to other controllers.

Use the following syntax with syncd:

syncd [-f] | [-E] | [-s]

The options for syncd are:

-f

Runs syncd in the foreground (normally runs as a daemon).

-E

Prints a lot of debugging messages to stderr while running.

-s

Starts in standby 3DNS mode. A 3DNS Controller started in standby 3DNS mode may switch to active mode after startup. Standby 3DNS mode means it receives changes to synchronized files, but does not synchronize local changes to remote 3DNS Controllers.

Actions

An action is an executable program or script that is run by syncd whenever a file is synchronized from a remote controller. Arguments for an action can be listed after the action, and if one of the arguments for the action is to be the actual file name itself, you can use the $path as the argument. Actions are run on files, not on directories (but on the individual synchronized files in the directory), and not on links (but on the file that the link points to). Each line of a sync list file consist of:

[token1|token2|...|tokenN] file_name [action] [action args]

Comments can be put in the sync list files, starting with #.

The sync list, /var/3dns/etc/sync_list , by default is empty. Also, no actions are allowed for any files listed in this sync list. This file is synchronized between controllers (meaning, if you add a new file to sync_list) the new file and sync_list will be synchronized to the remote controllers.

Here is an example of what you could put into sync_list :

# A config file that is backed up backup /etc/my_config # A directory with things that I want to sync and # be able to checkpoint ckpoint /var/my_stuff

The sync list /var/3dns/etc/sync_list.mandatory are the files that are synchronized for managing the 3DNS Controller configuration. The list should rarely require modification:

# This lists files that syncd will always sync # between 3DNS Systems and the actions that will # be run on the remote 3DNS systems: fixed backup /var/3dns/etc/wideip.conf 3dns_load $path # Synced include files directory fixed backup /var/3dns/include/sync/ # The extra commands files that may be produced # when a collector dumps (this is a directory). # The action is only run once the file first appears fixed once /var/run/sync_wideip_cmds/ 3dns_action $path # Namesurfer stuff fixed backup /var/f5/namesurfer/db/ ns_restart $path # Uncomment the next line if /etc/named.conf # should also sync #fixed backup /etc/named.conf 3ndc restart

The sync_list.named file is created when named starts up. It lists DNS zone files that need to be synchronized (if any). This file should not be modified by the user.

Checkpointing

A checkpoint is a saved version of the files that syncd synchronizes at a certain moment. Only files that have the backup or ckpoint token are checkpointed. If you later need to restore the state of a controllers configuration files, the checkpoint can be rolled back to restore the previous state of the controller. See the manual pages for syncd_checkpoint and syncd_rollback to see how to create and rollback a checkpoint.

Scripts

This section provides information on each script that is shipped with the 3DNS Controller. Many scripts correspond to commands on the 3DNS Maintenance menu, which is discussed starting on page 7 -1 . This section provides information about how the scripts work. If you plan on doing a scripted task manually, you should find this section especially helpful.

Note: Before you edit a script, make a backup copy of the original.

3dns_admin_start

The 3dns_admin_start script corresponds to the Restart 3DNS Web Administration command on the 3DNS Maintenance menu. This command restarts the 3DNS web server.

3dns_auth

All 3DNS Controller scripts are easier to use when you generate password authentication. The 3dns_auth script corresponds to the Generate RSA Authentication command on the 3DNS Maintenance menu.

Note: This script is not available in the international version of the 3DNS Controller.

The 3dns_auth script generates a password authentication copying the ssh key to each 3DNS Controller and BIG/ip Controller.

Warning: Before you use this command, you must set the RSAAuthentication parameter to yes in the /etc/sshd_config.conf file.

If no identity.pub file exists, 3dns_auth runs the ssh-keygen command to generate /root/.ssh/identity and /root/.ssh/identity.pub files that incorporate NULL passphrases. An existing identity.pub file indicates that ssh-keygen was already run. Running ssh-keygen more than once will cause problems, and is not recommended.

When you run ssh-keygen, press Enter when asked for a passphrase. Do not type in a password.

Here is a sample session to generate a public key:

3dns-receiver# ssh-keygen

Initializing random number generator...

Generating p: ............++ (distance 364)

Generating q: ..++ (distance 16)

Computing the keys...

Testing the keys...

Key generation complete.

Enter file in which to save the key (/root/.ssh/identity):

Enter passphrase:

Enter the same passphrase again:

Your identification has been saved in /root/.ssh/identity.

Your public key has been saved in /root/.ssh/identity.pub

To test that you have successfully generated the ssh key, use ssh to log into the principal 3DNS Controller without a password:

principal# ssh root@<ip-address-of-3DNS>

If you have an existing identity.pub file

If you have an existing identity.pub file, but you want to perform the other tasks performed by 3dns_auth, do not run the script again. Instead, append the contents of the /root/.ssh/identity.pub file to the 3DNS /root/.ssh/authorized_keys file, using the following command:

3dns-standby# cat /root/.ssh/identity.pub |\
ssh -l root <ip-address-of-3DNS> 'cat >> /root/.ssh/authorized_keys'

Note that you must use a front tick mark (also called a single straight quotation mark) in the above syntax.

3dns_dump

The 3dns_dump script saves the current state of the named cache into a new /var/3nds/etc/wideip.conf file.

3dns_sync_metrics

The 3dns_sync_metrics script corresponds to the Synchronize Metrics Data command on the 3DNS Maintenance menu. You should only use this script when you are configuring a new 3DNS Controller. This script prompts you to either copy metrics data from the local 3DNS Controller to other 3DNS Controllers, or from a remote 3DNS Controller to the local 3DNS Controller.

3dns_web_config

The 3dns_web_config script corresponds to the Reconfigure 3DNS Web Administration command on the 3DNS Maintenance menu. This script lets you make configuration changes to the 3DNS web server.

3dns_web_passwd

The 3dns_web_passwd script corresponds to the Change/Add Users for 3DNS Web Administration command on the 3DNS Maintenance menu. This script secures the 3DNS web server using basic authentication. This script lets you provide restricted or administrative access to the 3DNS web server for selected users only, and assigns passwords for those users. Users with restricted access have access to the statistics area only. Users with administrative access have access to all areas of the 3DNS web server.

Note: The 3dns_web_passwd script is run by the First-Time Boot utility. You can run this script again any time you need to provide access for another user.

3dnsmaint

The 3dnsmaint script opens the 3DNS Maintenance menu.

3dprint

The 3dprint script corresponds to the Dump and List named Database command on the 3DNS Maintenance Menu. This script lets you view these statistics screens on the command line:

• sum
  Displays summary statistics, such as the 3DNS Controller version, the total number of resolved requests, and the load balancing methods used to resolve requests.
• paths
  Displays path statistics, such as round trip time and packet completion rate.
• ldns
  Displays statistics collected for local DNS servers, including the number of resolution requests received from a given server, and the current protocol used to probe the server.
• vs
  Displays statistics about BIG/ip and host virtual servers, such as the server state, and the number of times it has received resolution requests.
• bigips
  Displays statistics about all BIG/ip Controllers known to the 3DNS Controller, including the number of virtual servers each BIG/ip Controller manages, and the number of times that the 3DNS Controller resolves requests to those virtual servers.
• hosts
  Displays statistics about all hosts known to the 3DNS Controller, including the number of times that the 3DNS Controller resolves requests to the host.
• wips
  Displays statistics about each wide IP defined on the 3DNS Controller, including load balancing information and the remaining time to live before the wide IP's metrics data needs to be refreshed.

3ndc

The 3ndc script starts the 3ndc utility, which is described on page B -4 . ndc is an alias for 3ndc.

big3d_check

The big3d_check script corresponds to the Check big3d command on the 3DNS Maintenance menu. This script checks that each BIG/ip Controller listed in the bigips.txt file is running the big3d agent.

big3d_install

The big3d_install script corresponds to the Install and Start big3d command on the 3DNS Maintenance menu. This script installs and starts the appropriate version of the big3d agent on each BIG/ip Controller. This script is useful for 3DNS Controller updates.

big3d_install performs the following procedure on each BIG/ip Controller:

1. Stops the running big3d agent process.
2. Uses a matrix file to determine which version of the big3d agent to copy to the BIG/ip Controller. The matrix file is a file that lists version numbers for all BIG/ip Controllers known to the 3DNS Controller and the version numbers of the big3d agent and named utility running on each BIG/ip Controller.
3. Adds the following to the bottom of the /etc/rc.local file:

if [ -f /usr/sbin/big3d ]; then echo -n "big3d": /usr/sbin/big3d 2> /dev/null fi

1. Starts /usr/sbin/big3d.

   For configuration options, see big3d on page B-14.

big3d_restart

The big3d_restart script corresponds to the Restart big3d command on the 3DNS Maintenance menu. This script stops and restarts the big3d agent on each BIG/ip Controller.

big3d_version

The big3d_version script corresponds to the Check versions of named, BIG/ip kernel and needed big3d command on the 3DNS Maintenance menu. This script displays version numbers for all BIG/ip Controllers known to the 3DNS Controller, as well as the version numbers of the big3d agent and named utility running on each BIG/ip Controller.

edit_lock

The edit_lock script lets you safely edit a specified file that is synchronized between 3DNS Controllers in a sync group. This script creates a temporary version of the original file, and this temporary file replaces the original file when you are finished editing it. If you do not use this script to edit a file, there is the danger that a partial file might be synchronized to other 3DNS Controllers in the sync group.

To use this script, type the following:

edit_lock <file name>

edit_wideip

The edit_wideip script corresponds to the Edit 3DNS Configuration command on the 3DNS Maintenance menu. This script opens the wideip.conf file for editing, copies it to all other 3DNS Controllers in the local 3DNS Controller's sync group, and restarts named.

install_key and F5makekey

The install_key script corresponds to the Generate and Copy F5 iQuery Encryption Key command on the 3DNS Maintenance menu. This script starts the F5makekey script and generates a seed key for encrypting communications between the 3DNS Controller and BIG/ip Controller. The install_key script creates and distributes the iQuery key to all BIG/ip Controllers and other 3DNS Controllers on your network.

Note: This script is not available in the international version of 3DNS Controller.

To start the F5makekey script, type the following from /usr/contrib/bin:

f5makekey

The seed value is located in /etc/F5key.dat and contains a random length (12-52) of random content (1-255), created by F5makekey. This array of values is used by MD-160, a one-way hash function, to generate a key (7 characters in length) for the Blowfish encryption algorithm.

syncd_checkpoint

The syncd_checkpoint script corresponds to the Checkpoint synced files command on the 3DNS Maintenance menu. This script creates a checkpoint file. A checkpoint file is a compressed tar file that contains an archive of the files that are synchronized.

You can run this script with or without arguments. If you run syncd_checkpoint without specifying arguments, the script creates the following default checkpoint file:

/var/3dns/staging/checkpoint/default.tar.gz

Note: All checkpoint file names have a .tar.gz suffix.

The syncd_checkpoint script can take the following optional arguments:

syncd_checkpoint [-c <name>] [ -i]

The options for syncd_checkpoint are defined as follows:

-c <name>

Creates a checkpoint file with the specified file name. You can also specify a non-default path for the file, unless the path starts with a slash (/). The default path for checkpoint files is /var/3dns/staging/checkpoint/. The syncd_checkpoint script automatically appends a .tar.gz extension to the end of the file name.

-i

Runs the script in an interactive session, which means that you are prompted for a file name.

syncd_rollback

The syncd_rollback script corresponds to the Rollback checkpoint command on the 3DNS Maintenance menu. This script unrolls a checkpoint file, which contains an archive of all synchronized files. This has the effect of replacing the current files with the files archived in the checkpoint file.

The syncd_rollback script can take the following optional arguments:

syncd_rollback [-c] [-c <name>] [-r] [-u] [ -i]

The options for syncd_rollback are defined as follows:

-c

Unrolls the most recently created checkpoint file, whether it is in the default location or elsewhere.

-c <name>

Unrolls the specified checkpoint file, whether it is in the default location or elsewhere. It is not necessary to end the name with .tar.gz, as this suffix is assumed.

-r

The archived files are restored with their old timestamps. This means that if any of the synchronized files were updated on a remote 3DNS Controller, the updated files will overwrite any older files contained in the checkpoint file.

-u

The archived files are restored with updated timestamps with the current time. This means that the files in the checkpoint are synchronized to the remote 3DNS Controllers and overwrite the existing files on the remote 3DNS Controllers.

-i

Runs the script in an interactive session, which means that you are prompted for option information.

Note: When you run this script from the command line, you must use the
-r, -u, or -i option.

syncd_start

The syncd_start script corresponds to the Restart syncd command on the 3DNS Maintenance menu. This script restarts the syncd daemon if it is already running, or starts it if it is not.

You can run this script with or without arguments. If you run syncd_start without specifying arguments, the script starts or restarts syncd.

The syncd_start script can take the following optional arguments:

syncd_start [-c] [-c <name>] [-r] [-u] [ -i]

The options for syncd_start are defined as follows:

-c

Before restarting syncd, unrolls the most recently created checkpoint file, whether it is in the default location or elsewhere.

-c <name>

Before restarting syncd, unrolls the specified checkpoint file, whether it is in the default location or elsewhere. It is not necessary to end the name with .tar.gz, as this suffix is assumed.

-r

Restores the archived files with their old timestamps. This means that if any of the synchronized files were updated on a remote 3DNS Controller, the updated files overwrite the rolled back files.

-u

Restores the archived files with updated timestamps to the current time. This means that the files in the checkpoint file overwrite any updated files on remote 3DNS Controllers.

-i

Runs the script in an interactive session, which means that you are prompted for option information.

Note: When you use the -c option, you must also use either the -r or -u option.

syncd_stop

The syncd_stop script corresponds to the Stop syncd command on the 3DNS Maintenance menu. This script stops the syncd daemon, if it is running.

You can run this script with or without arguments. If you run syncd_stop without specifying arguments, the script simply stops syncd.

The syncd_stop script can take the following optional arguments:

syncd_stop [-c] [-c <name>] [ -i]

The options for syncd_stop are defined as follows:

-c

Creates a checkpoint file in the default location before stopping syncd.

-c name

Creates a checkpoint file with the specified name and path before stopping syncd.

-i

Runs the script in an interactive session, which means that you are prompted for option information.