Netmagis

Import DNS data

Contents

• What's new
• Introduction
• Specifications
• Documentation
• Support
• Download
• Screenshots
• Demonstration
• Development
• License

Import existing DNS data into your Netmagis database

This documentation describes how to feed your database with referential data (users, groups, networks, organizations, etc.) as well as reuse your existing DNS zones if any.

Prerequisites

In order to import data, the following prerequisites are mandatory:

• the database package is installed and the database is created
• the www packages is installed and the application authentication is configured as described in the installation documentation.

It is assumed that the database is created, but empty (created with the .../sbin/netmagis-dbcreate program), and the Web application is configured for the correct authentication.

Note: the database is always initially created with internal PostgreSQL authentication. If you import your data with PostgreSQL authentication active, users will be created in the internal authentication system. If you later switch to LDAP authentication, internal authentication data will simply be ignored. So, you may import data by re-creating database each time with an internal PostgreSQL authentication, and later switch to LDAP authentication.

Check and validate your zones

Importing your existing DNS data is a time consuming task. You should check all your DNS zones with tools such as ZoneCheck. Time spent in checking and correcting your existing zones will greatly reduce manual work to import your data.

May I insist? This is an important task to do before importing data. Truly.

The .../share/examples/netmagis directory is the starting point for importing your data. Make a copy of all files in a working directory.

Build data

You need first to describe all referential data. Please, build these files according to your configuration. The next section will explain how to import your files.

If you don't want to use your existing zone files, provide other files (especially the network.txt, group.txt and domain.txt) in order to have

File network.txt

The network.txt file is central: it describes all your networks. Each network has the following attributes:

Attribute	Description
name	Short name of the network
address	IPv4 and/or IPv6 address of your network. You may have up to two addresses, one for IPv4 and one for IPv6.
gateway	IPv4 and/or IPv6 gateway address for this network. You may have up to two addresses, one for IPv4 and one for IPv6.
comment	One-line description of your network
org	Name of organization using this network. This name will be added to the organization list.
community	Name of a "community". In the Web application, you will find a drop-down menu for each network allowing you to categorize this network. Use it as you want.
location	Short string describing, if applicable, the location of your network.
groups	Name of all groups (see the group.txt file below) allowed to manage hosts (declare, edit, remove) in this network.
dhcp	Enable DHCP on this network, and optionally provides dynamic ranges specification

Each network described in this file should be a proper "broadcast domain". For example, if you have a /24 network that you splitted in two distinct VLANs, each of size /25, use 2 distinct /25 networks in this file.

Even if you want to restrict some groups to just a few addresses, name all allowed groups for each network. For example, if for a /24 network, you want group g1 be restricted to addresses 1 to 100, and group g2 be restricted to addresses 101 to 254, name g1 and g2 as groups for this network. After having imported your data, you will adjust access rights for g1 and g2 through the Web application.

To enable DHCP on a network, use dhcp= with at least a domain name and any number (may be 0) of IPv4 address ranges. If you just provide an empty declaration, DHCP will not be enabled. If you don't provide any address range, the value of the domain name if not important.

File group.txt

The group.txt file describes all your groups and users.

Each line of this file has the format:

group-name     login ... login

The group wheel is created, with admin privileges, by default by the netmagis-dbcreate program when

Each user is created in the authentication database if you enabled it. If you use LDAP authentication, it is assumed that your users already exist in your directory (the import program does not check existence).

File domain.txt

The domain.txt file describes all your existing domains and permissions.

Each line of this file has the format:

domain-name SET priority group ... group

domain-name ALLBUT priority group ... group

The ALLBUT directive for a domain tells that all groups are allowed to access this domain (with the priority giving the rank in the menu, as before), except those which are cited.

File mailrelay.txt

The mailrelay.txt file describes all mail relays (MX) for your domains (they are not read from your zone files). For each domain, you must provide all your relays with associated priority (as in MX resource records).

Warning: this file must be imported when all your zone files are imported, since it references hosts which must already exist in your database.

If you happen to have a mail relay outside of your domains, don't reference it in this file. After importing your data, you will be able to add it manually.

File mailrole.txt

If you use Netmagis to provide mail routing inside your domains, you need to build a mailrole.txt file where you will provide one line for each mail address:

mail-address       mailbox-host

The mail-address is the right part of a mail address. For example, suppose that you want to route mail addressed to *@marketing.example.com to the somehost.example.com, you will provide a line such as:

marketing.example.com       somehost.example.com

Warning: this file must be imported when all your zone files are imported, since it references hosts which must already exist in your database.

File rrsup.txt

You surely don't want to provide such a file. It is used to provide some MX resource records for each declared name, which is no longer considered as a good practice.

Zone files

Did you checked and validated your zone data? Are you sure?

So, since your zone data are correct, make a copy of your zone files (every zone served by your BIND server, even reverse IPv4 and IPv6 files) on the database server.

You may have to rearrange your zone files in order to begin with the zone "prologue", which will contains everything which is not a host definition, and the remainder of the zone which is only A, AAAA or CNAME resource records. Please note that record names (i.e. host names, on the left) in the second part of the file must not contain dots (".").

On each file, you will need to perform some actions:

• first, make sure the serial number (in SOA record) is of the form YYYYMMDDnn (as recommanded by RFC 1912, page 3)
• put your serial number on a separated line and append the following comment to the line:

  ; serial

  such that the serial may be localized in the zone prologue
• insert a line beginning with:

  ; CUT HERE

  to delimit prologue and host definitions
• make sure that every host referenced in the right part of a CNAME resource record has been defined in a zone file

Import your data

When you built all files, you may now use the .../sbin/netmagis-dbimport program. It is recommanded that you automate the import step by copying and modifying the .../share/examples/netmagis/run-all.sh script.

If you want to re-create the Netmagis database with netmagis-dbcreate each time the script is run, make sure you add identity of the PostgreSQL administrator user using the -u and -w switches, as described in the installation documentation. Else, remove this line.

You may remove lines if you don't want to import some data (zone files, mail relays, etc.).

For zone import, arguments to the netmagis-dbimport are as follow:

netmagis-dbimport -v zone domain-name file-name selector rrsup user

with:

• -v means "verbose"
• zone tells the script that this is a zone (normal or reverse) import
• domain-name is the domain name of the zone
• file-name is the file containing the zone data
• selector is either a domain name (for a normal zone file) or an address with a prefix (for a reverse IPv4 or IPv6 zone
• rrsup is probably not used, so use /dev/null to provide an empty file
• user is the name of an existing Netmagis user (see the group.txt file) which will be the initial owner of all hosts. You may use a fictive user (providing it has been defined in the group.txt file).

Run the run-all.sh and watch the results. Correct errors, if any.

Testing your data

You should see your data through the Web interface.

Netmagis allows you administrators to substitute for another user in order to see what she/he sees. In order to use this facility, append the following string to a Netmagis URL:

?uid=login     or     &uid=login

http://yourhost/netmagis/index?uid=joe

Using this facility, you may check that Netmagis users don't have acess to more information than they are authorized to.

Congratulations, the most difficult part of the installation is now done!