Netmagis
| 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 ... loginThe group-name should be referenced in the network.txt file. Each user must belong to one group only.
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 view.txt
The view.txt file describes all your existing views and permissions.
Each line of this file has the format:
view-name SET priority group ... groupor:
view-name ALLBUT priority group ... groupThe view-name is the name of the view, which may be cited more than once. The SET directive specifies that members of the cited groups have access to this view (i.e. may declare, edit or remove hosts), and the priority is the rank of this domain in the drop-down menus (first items are numerically lower).
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.
Please note that this file is needed even if you don't use multiple views. In this case, this file must contain only the "default" view:
default SET 100 group ... group
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 ... groupor:
domain-name ALLBUT priority group ... groupThe domain-name is the name of the domain, which may be cited more than once. The SET directive specifies that members of the cited groups have access to this domain (i.e. may declare, edit or remove hosts), and the priority is the rank of this domain in the drop-down menus (first items are numerically lower).
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.
This file is loaded in the context of a view, which should be the most public view, since mail relays are advertised as MX records on the Internet.
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[/view]
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
You can specify an optional view for mailbox-host. This file is loaded in the context of a view (which should be the most public view), but the mailbox-host may be located in a different view.
For example, you may want to advertise a mail address in a public (e.g. external) view, but route to an internal host. You will thus have a line which looks like:
marketing.example.com somehost.example.com/internaland the file will be loaded in the context of the "external", referencing a host which exists in the "internal" view.
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:
- 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. Note that your serial number need not to conform to the "yyyymmddnn" convention. - 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 view-name domain-name file-name selector rrsup user
with:
- -v means "verbose"
- zone tells the script that this is a zone (normal or reverse) import
- view-name is the view name in which the data will be loaded
- 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=logindepending on the context. For example:
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!