IRC Services Manual

5. Importing and exporting databases

5-1. Exporting Services databases in XML format
5-2. Importing (merging) data from an XML file
5-3. Converting data from other Services-like programs
    5-3-1. Using the convert-db program
    5-3-2. Notes on converting databases from particular programs

Table of Contents

5-1. Exporting Services databases in XML format

In order to facilitate processing of the Services databases by other programs, Services provides the ability to export the databases in XML format. This is accomplished through the misc/xml-export module and, optionally, the HTTP server built into Services.

The misc/xml-export module adds an extra command-line option, -export, to Services. Since the command line is parsed before Services connects to the network, the module must be specified in your ircservices.conf file to enable this option. The option has the format "-export" or "-export=filename", where filename is the name of the file to write the XML data to; if it does not begin with a slash, it is taken to be relative to the Services data directory (the directory containing the database and log files). If filename is not given or is a single hyphen ("-"), the data will be printed on standard output. When the export completes, Services will terminate, and will not connect to the IRC network. This action can be performed while another copy of Services is running, but the output will not include changes made online since the last time the databases were saved to disk. (It is also possible for the running copy of Services to report a "data directory locked" error if it tries to save the databases while the export operation is in progress. This is harmless; you can force the databases to be written after the export completes by using the OperServ UPDATE command, but do not use the FORCE option while the export is still running as this may result in corrupted database files.)

Additionally, if the misc/xml-export module is loaded into Services, the HTTP database access module (httpd/dbaccess) will display an "XML database download" link. Clicking on the link will display the XML data in your browser, which you can then save (for Netscape and Internet Explorer, select "Save as..." from the browser's File menu). Alternatively, you can download the link directly without displaying it in your browser; in Netscape, hold shift while clicking on the link, and in Internet Explorer, right-click on the link and select "Save target as..." from the pop-up menu.

The format of the exported XML data is described in Appendix B. No DTD is currently available.

Notes: Services will not respond to any network activity while you are downloading the database. If you have a large database, this can make Services appear to "freeze" with respect to the IRC network, and it may even get disconnected from the network in extreme cases. Additionally, be aware that the data may change after you have downloaded it; if you want to avoid this, for example when exporting data to move it to another machine or network, use the command-line option -export (after shutting Services down) rather than the HTTP server interface.

Note to Internet Explorer users: Some versions of Internet Explorer have a bug which can prevent the XML data from being displayed or downloaded properly. If you have this problem, use another browser, or add the following key to your registry using the Registry Editor (regedit), as described in Microsoft Knowledge Base article Q239750 [support.microsoft.com]:

Key:  HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings
Value name: IsTextPlainHonored
Value type: DWORD
Value data: HEX 0x1
Improper use of the Registry Editor can cause your system to malfunction, so be careful when making any changes. You may also need to upgrade your system files as described in the Knowledge Base article linked to above if you are using Windows 95, Windows 98, or Windows NT 4.0.

Back to top

5-2. Importing (merging) data from an XML file

Just as it can export data in XML format, Services can also read in XML data and import (merge) it into its databases. Importing is handled by the misc/xml-import module. Unlike exporting, however, importing cannot be done via the HTTP server; it is always done through the command line. For this reason, the misc/xml-import module must be loaded at startup (loading it via an OperServ REHASH or a SIGHUP signal will have no effect).

To import a set of data stored in XML format into Services, start Services with the command-line option "-import=filename", where filename is the name of the file containing the data; if it does not begin with a slash, it is taken to be relative to the Services data directory. Services will parse the data file, and if no errors are found, the data will be merged into Services' databases and the program will terminate. If problems are found, they will be printed on standard output and the databases will not be modified.

Normally, if nickname or channel "collisions" occur—that is, if a nickname or channel in the input data is already registered in Services' databases—Services will skip over that nickname group or channel, respectively. (For nicknames, the entire nickname group is skipped to prevent cases where, for example, a user's secondary nick is available but the primary nick is registered to someone else.) This behavior can be modified by the OnNicknameCollision and OnChannelCollision options in modules.conf. Additionally, Services can be made to output a list of all data imported by setting the VerboseImport option (which is set in the example modules.conf provided with Services).

Note that the maximum user count, OperServ SU password, and news items will not be imported. Also, any autokills, session limit exceptions, or S-lines which collide with those in the database will be automatically skipped.

Back to top

5-3. Converting data from other Services-like programs

5-3-1. Using the convert-db program

For users of other Services-like programs who want to switch to IRC Services, a program called convert-db is supplied to convert databases used by such programs into XML data files, which can then be imported into Services as described in section 5-2 above. This program is installed into the Services data directory (/usr/lib/ircservices for binary distributions, /usr/local/lib/ircservices by default for source distributions).

In its simplest form, convert-db takes the pathname of the directory containing the database files to convert on the command line, and writes the converted XML data to standard output. A typical invocation might look like this:

convert-db /usr/local/lib/someprogram > someprogram.xml
convert-db will look at the files in the directory given and attempt to determine automatically what program created them; if this succeeds, it will proceed to read in the database files and convert them to XML. If convert-db cannot determine what program created the files, you can tell it explicitly by adding a +program-name option in front of the path name (see the full syntax description below for valid values for program-name).

Note that not all features of all programs are supported by Services, and some settings may be lost when you import data. See section 5-3-2 below for information on particular programs, and section 5-2 for notes on importing the converted data into Services.

The full syntax for convert-db is as follows:

convert-db [-v] [+program-name] [options . . . ] pathname
The options and parameters are:
program-name Name of program Supported versions
anope Anope Services [www.anope.org] All versions
auspice Auspice Services 2.5 and later
bolivia Bolivia IRC Services 1.2.0
cygnus Cygnus [www.habber.net] 0.2.0
daylight Daylight 12
epona Epona IRC Services 1.3.0 and later
hybserv HybServ All 1.x versions
ircs-1.2 Internet Relay Chat Services (IRCS) 1.2, 1.3
magick-1.4 Magick IRC Services (Magick I) 1.4
ptlink PTlink Services [sourceforge.net] 2.13.0 and later
sirv SirvNET Services [www.sirv.net] 2.9.0 and earlier
trircd-4.26 trircd IRC Services 4.26
wrecked-1.2 WreckedNet IRC Services 1.2.0

Table 5-1. Values for +program-name parameter to convert-db

Additional options are available for the following data file types:

cygnus

hybserv

Back to top

5-3-2. Notes on converting databases from particular programs

Note that this is not a comprehensive list of differences; only the major differences and types of data that cannot be converted are listed.

All programs

Anope

Auspice

Bolivia

Cygnus

Daylight

Epona

HybServ

IRCS

Magick I 1.4

PTlink

SirvNET

trircd

Wrecked 1.2.0

Back to top

Table of Contents | Previous section: Services command reference | Top | Next section: Adding features to Services