# IRC Services Technical Reference Manual

## 9. The database conversion tool

Previous section: Other modules | Table of Contents | Next section: Compilation

### 9-1. Purpose and usage

The database conversion tool `convert-db` is designed to allow users of other Services-like programs to migrate data stored with the other program into Services. This program serves as an adjunct to the main `ircservices` executable, reading in database files produced by foreign programs and writing out an XML file that can then be imported into Services with the `misc/xml-import` module (see section 8-4-2).

More information (from a user's point of view) can be found in section 5-3 of the user's manual.

As a historical note, this tool was introduced in version 4.1 of Services as `import-db`, and overwrote the existing Services databases with the imported data. This behavior was changed for version 5.0, both to dissociate the tool from the particular database format used by Services (which was still limited to the old binary format at the time, though implementation of a new format was planned) and to allow merging of data rather than simple overwriting. The tool's name was also changed to `convert-db` at this time to reflect the fact that it no longer performed the actual importing.

Back to top

### 9-2. Structure

The `convert-db` tool can be divided into two main parts: the main program, which calls out to individual formats' probe and load routines, sanity-checks the loaded data, and writes out the XML data; and the format handlers, which process data produced by particular programs.

All source code for `convert-db`, with the exception of code borrowed from the main program, is located in the `tools` directory.

Back to top

#### 9-2-1. The main program

The overall database conversion processing is performed in the `convert-db.c` source file. The `main()` routine performs the following functions:

- Initializes variables and processes command-line parameters.
- Checks that the database file directory given on the command line is accessible, and expands the pathname to an absolute path if the specified path is relative.
- If no database type was given on the command line, calls each format handler's `check()` function, which determines whether the files contained in the specified directory are of that particular format. The first format found is used (if no format is found, the program aborts).
- Calls the selected format's `load()` function to load the databases.
- Performs sanity checks on the loaded data (via the `sanity_checks()` function), to ensure that erroneous data is not output.
- Calls `xml_export()` (from the `misc/xml-export` module, linked into the final program) to write the XML data to standard output.

`convert-db.c` also links in `compat.c` and `misc.c` from the core code, making all of their functions available to format handlers, and implements several other utility functions, including simple versions of some core functions:

- `smalloc()`, `scalloc()`, `srealloc()`, and `sstrdup()` from `memory.c`;
- `init_password()` and `clear_password()` from `encrypt.c`;
- `makenick()` from NickServ and `makechan()` from ChanServ to initialize and add nicknames and channels to the database;
- `open_db_ver()` to open an old-Services-style database file and check its version number;
- `get_nickgroupinfo_by_nick()` to retrieve a `NickGroupInfo` structure directly from a nickname;
- `set_os_priv()` to set the `os_priv` nickname group field for a nickname without having to first retrieve the `NickGroupInfo`; and
- `convert_acclev()`, to convert pre-Services 5.0 channel access levels to levels used by the current version.

The nickname, channel, and other databases themselves are implemented as simple linked lists, since efficiency is not seen to be a significant concern for `convert-db`. Also, since the program exits immediately after writing out the converted data, no special effort is made to keep track of or free allocated memory; it is assumed that the operating system or library cleanup code will take care of freeing resources.

Back to top

#### 9-2-2. Format handlers

Format handlers perform the bulk of the conversion work. Each format is defined by a `DBTypeInfo` structure containing an identifying string for the format (used to match against the `+program-name` command-line option), a `check()` routine which determines whether a given directory contains databases in the format, and a `load()` routine which loads databases from a given directory. The list of available formats is hard-coded as a list of external structure variable names in `convert-db.h`, which is used in `convert-db.c` to initialize an array of formats. The structures and routine implementations themselves are stored in separate source files (see section 9-3 below).

The `check()` routine takes a single parameters, `const char *dir`, the path to the directory to be checked. The routine should check to see if a database in a recognized format is contained in that directory; if so, the routine should return a string describing the database format (usually the name, and version if known, of the program that created it), which will then be displayed to the user. If no recognized database is found, the routine should return `NULL`.

The `load()` routine takes four parameters:

- `const char *dir`: The directory to load data from.
- `int verbose`: Whether the `-v` (verbose) flag was passed to `convert-db`.
- `int ac, char **av`: Any unrecognized command-line options. `ac` is the number of options, and `av[]` is an array of pointers to the option strings, with `av[0]` pointing to the program name as for `main()`.

The command-line option array is passed in addition to the source directory and verbosity flag to allow individual database loaders to implement their own options. For example, the Cygnus database takes advantage of this to add options for timezone handling.

The `load()` routine is assumed to succeed; if an error occurs that prevents the data from being loaded properly, the routine should simply call `exit(1)` to abort the program.

Additionally, the file read/write utilities from `modules/database/fileutil.c` (see section 6-5-1) are linked into `convert-db` and can be used by the `check()` and `load()` routines.

Back to top

### 9-3. Supported database formats

`convert-db` supports loading data from a total of 13 different programs. The data loading code is in the various `convert-*.c` files, one file for each distinct format (several programs use similar database formats and therefore share code). Each of these files is discussed below.

In general, each format's `load()` routine is implemented as a function which calls subfunctions for each file to be loaded. Since most of the programs are based on old versions of Services, the contents of the files correspond fairly well with Services itself.

Where binary database files include fixed-length buffers, the lengths of those buffers are assumed to be the same as those in the distributed source code, with no changes to any configuration settings. For example, most IRC service programs default to a nickname buffer size of 32 bytes, and `convert-db` assumes that that value has not been changed by the user.

Back to top

#### 9-3-1. `convert-cygnus.c` (Cygnus)

Cygnus is an IRC service program based on an old version of Services; development seems to have stopped as of the writing of this manual. Unlike the other programs supported by `convert-db`, Cygnus stores its databases in plain text files, with each line containing a two-character field identifier and one or more values, all separated by spaces. As such, the data processing is somewhat more complex than for other databse formats, particularly for numeric values, which must be checked for syntactic validity as well as range. The following utility routines and macros are used by the various loading functions:

- `cyg_strtok_remaining()` returns the remainder of the string currently being processed by `strtok()` with any leading whitespace removed, like `strtok_remaining()` from `misc.c` in the core code; in addition, any trailing newline (CR or LF) is removed.
- `CVT_TIME(var, str, errfmt, ...)` attempts to convert the string in `str` to a `time_t` value. If the conversion succeeds, the value is stored in `var`, which must be an lvalue; if it fails (because the string does not represent a valid integer—range checks are not performed), `var` is set to the current time, and the error message in `errfmt`, along with any additional parameters, are printed to standard error.
- `CVT_TIME_0(var, str, errfmt, ...)` does the same thing as `CVT_TIME()`, but defaults to zero rather than the current time when the string is invalid.

Cygnus also supports storing time zone information with each nickname, like NickServ `SET TIMEZONE` in Services; however, rather than storing the actual time offset, Cygnus stores an index into a table whose contents are controlled by a configuration file. The default list of time zone offsets is included in the `default_timezones[]` array, but since users may have modified the time zone configuration, the command-line option `-tzfile=filename` is checked for by the `load()` function, allowing the user to specify their configuration file, which is then loaded and used in place of the default list; `-no-timezones` (which causes all time zone data to be discarded) is also supported as a fallback in case time zone importing results in incorrect data.

Cygnus does not have a "default" value, like `MEMOMAX_DEFAULT` in Services, for the memo limit field, but instead stores the actual value of the default limit at the time the nickname is registered. As a result, these values will remain constant in Services even if the `MSMaxMemos` configuration setting is changed. To work around this, the `-reset-memo-limits` command-line option is checked for, and if present, all memo limits are reset to `MEMOMAX_DEFAULT`.

The data files are as follows:

- `nickserv.db`: Nickname database. The file contains three file-level fields:
  NV version
    File version. This field is always the first line in the file. The version number is 3 in Cygnus 0.2.0.
  SS stamp
    Previous servicestamp value. Cygnus stores this value in the database, allowing it to ensure (assuming the database is not modified) that servicestamp values are not reused even if the program is restarted. Services does not save this value, so it is ignored.
  DE nick-count link-count memo-count
    "Database end". Included as the last line in the file, and contains counts of nicknames, links, and memos stored in the database. These can be used to double-check that all data was loaded correctly.

  All other fields are subfields of a nickname record (a nickname group record, in Services terminology):

  NI nickname password time-registered last-seen last-timestamp last-servicestamp flags memo-limit timezone-index key last-usermask last-realname
    Begins a nickname record; all subsequent fields until the next `NI` or the end of the file correspond to this nickname. Most of the fields are self-explanatory, with times recorded as integers using ordinary Unix `time()` values. If the `nickname` too long to fit in a `NICKMAX`-character buffer, it is truncated with a warning. The `last-timestamp` field is not saved by Services, and is thus ignored; the `last-servicestamp` field will not have any relevance to servicestamps assigned by Services, and is likewise discarded. `timezone-index` is an index into a table of time zone offset values (see the discussion of time zones above). The `key` is the equivalent of the authentication code used by the `nickserv/mail-auth` module, and is used to set the nickgroup's `authcode` field, so that authentication codes stored with nicknames will continue to be valid; the code is assumed to be for a new registration, unless we find out otherwise later on. If the `NI` line does not match the above format or the nickname already exists, the entire nickname record is discarded.
  AC mask
    An access mask for the current nickname.
  LN nickname-1 nickname-2...
    The list of subnicks (linked nicks) for the current nickname. These are added to the current nickname group's nick list, with a new `NickInfo` structure created for each subnick. As width `NI` processing, nicknames that do not fit in a `NICKMAX`-character buffer are truncated with a warning, and nicknames that collide with already-existing nicks are discarded. In theory, any number of nicknames can be included in a single `LN` line, but Cygnus (version 0.2.0, at least) uses a 2048-byte line buffer when writing the databases; this routine uses a 4096-byte buffer, so there should be no truncation problems.
  MO num flags time sender text
    A memo for the current nickname. The `text` parameter may include spaces.
  FW nickname
    The nickname to which memos to this nick should be forwarded. Services does not support forwarding memos to another nickname, so this field is ignored.
  FR reason
    Freeze (suspension) reason for the nickname.
  EM address
    E-mail address for the nickname.
  TE address
    An E-mail address which has been set with `SET EMAIL` but not yet authenticated. If this field is found, then the nickname's authentication reason is set to `NICKAUTH_SET_EMAIL`, and a new authentication code is generated if one does not already exist (perhaps because of a corrupt database file). The E-mail address given in the `EM` field is moved to `NickGroupInfo.last_email` as well.
  UR address
    URL for the nickname.
  UN address
    User information field for the nickname (instant messenger UIN); ignored.
  NA address
    User information field for the nickname (real name); ignored.
  AG address
    User information field for the nickname (age); ignored.
  SX address
    User information field for the nickname (sex); ignored.
  LO address
    User information field for the nickname (location); ignored.
- `chanserv.db`: Channel database. As with `nickserv.db`, the file begins with a version field (`CV` in this case; the supported version is 3) and ends with a `DE` field containing a channel count. There is also a `VF` field (taking two parameters, a channel name and time value) listing channels which have been registered but not verified, but since Services does not implement such a verification system, these records are ignored. Channel records are stored on multiple lines:
  CI channel founder password time-registered last-used flags mlock-on mlock-off topic-lock memo-level key
    Begins a channel record. The channel name is truncated to fit in a `CHANMAX`-character buffer, if necessary. The channel is discarded if the `CI` line is invalid, if another channel with the same name already exists, or if the founder is not a registered nickname. The mode lock parameters `mlock-on` and `mlock-off` are mode bitmasks, which are converted to mode strings based on the Cygnus mode flag constants. The `topiclock` and `memolevel` parameters are access levels required for setting the topic and receiving channel memos, respectively, using the same system as channel access entries (see below), with zero indicating that the feature is disabled. In Services, topic-lock is an on/off setting, so the `TOPICLOCK` channel flag is set if `topiclock` is nonzero; the `memolevel` value is translated directly to the `CA_MEMO` privilege level. Services does not require authentication for channels, so the `key` parameter is ignored.
  CA nick-or-mask level
    Channel access entry. Cygnus, like versions of Services before 3.0.0, allows both nicknames and usermasks on channel access lists; any access entry that does not correspond to a registered nickname is therefore discarded. Cygnus uses a simple XOP-based access system, with five levels:
    - 1: VOP
    - 2: HOP
    - 3: AOP
    - 4: SOP
    - 5: Founder
    These values are translated to the corresponding `ACCLEV_*` constants.
  AK mask setter time reason
    Channel autokick entry. The setter nickname is truncated (silently) if necessary.
  SU nickname
    Channel successor. Ignored if the nickname is not registered or is in the same nickname group as the founder.
  GR text
    Channel greeting (entry message). `text` may contain spaced.
  UR url
    Channel URL.
  CT setter time topic
    Channel topic, along with the nickname of the topic setter and the time the topic was set.
  KY key
    Channel key locked with `MLOCK`. Ignored if mode `+k` is not locked on.
  LM limit
    Channel limit locked with `MLOCK`. Ignored if not a valid limit value, or if mode `+l` is not locked on.
  FL value
    Channel flood setting locked with `MLOCK`. Ignored if mode `+f` is not locked on.
  LK link
    Channel link locked with `MLOCK`. Ignored if mode `+L` is not locked on.
- `rootserv.db`: Contains global data, analogous to the OperServ and related databases in Services. Data is stored with one full record per line, as follows:
  AK mask setter is-realname set-at expires reason
    An autokill or SGline record; the numeric field `is-realname` determines the record type (nonzero for an SGline, zero for an autokill). `reason` may contain spaces.
  TR mask limit
    A session exception with a defined user limit (a "trigger" in Cygnus terminology).
  EX mask
    A session exception with no user limit.
  NW time
    The last time the `RESETNEWS` command was called. Cygnus implements news as a simple text file, shown to users only if the user's last read-news time is earlier than this timestamp. Ignored.
  RS max-uptime
    The longest amount of time Cygnus has remained running, in seconds. Services does not store this information, so this field is ignored.
- `web.db`: Contains a summary of all data, intended for use by external programs. Apparently serves a purpose similar to the XML export functionality in Services. This file is ignored.

Back to top

#### 9-3-2. `convert-epona.c` (Epona, Anope)

Epona IRC Services is an IRC service program based on Services 4.3.3; development has been intermittent since the release of Epona 1.4 in 2001. Anope Services was forked from Epona 1.4.14, and has been developed more actively. Both use a database format similar to the Services 4.3 format; however, rather than a single format version number for all files, individual version numbers are used for each file. (As noted in the user manual, versions of Anope since 1.7.11 also support storing databases in a MySQL database; access to such databases is not supported by the `convert-db` tool.)

Epona and Anope use a "nick core plus nick aliases" concept for registered nicknames, in which most nickname data is stored with a single "core" nick and other nicknames can "aliased" to the same settings (the redesigned nickname linking system in Services 5.0 was based on this concept). Other data is structured similarly to Services, and conversion is fairly straightforward.

Anope supports a number of IRC servers; unfortunately, the flag values used in the channel mode lock fields stored in the database vary between IRC servers (though given the vast range of channel modes present in various servers, this is probably unavoidable). In order to interpret the mode flags correctly, the converter allows a "`-ircd=`" option to be passed on the command line. The parameter to this option selects the IRC server type to be used for interpreting channel modes. If no `-ircd` option is given, the converter only converts the eight basic channel modes (`i`, `k`, `l`, `m`, `n`, `p`, `s`, `t`), which share the same flag values across all IRC server types.

Since Anope 1.7.18, administrators can select one of several encryption modules, similar to how encryption was handled in Services 5.0. This method shares the same shortcoming present in Services 5.0, however, which is that a particular password's encryption status cannot be determined from the data itself. To work around this problem, the converter accepts a command-line option "`-encryption=`" to select the type of encryption used for passwords in the databases. If this option is given, the "encrypted" flag on nickname cores and channels is ignored, and all passwords are assumed to use the given encryption type; otherwise, the "encrypted" flag selects between MD5 encryption and no encryption. (For forward compatilibity, `sha1` is accepted to indicate SHA-1 encryption, but Services will not be able to check such passwords without a third-party module implementing the SHA-1 hash.)

The Epona/Anope database files are:

- `nick.db`: Contains nickname data. Nickname cores are stored in a format similar to that in Services 4.x, followed by nickname aliases in a condensed format. Unlike Services, Epona and Anope store nicknames and passwords as strings rather than buffers (with the exception of the memo sender field, which is stored as a buffer of default size 32 bytes); there seems to have been a bug in some versions of Epona that could result in a `NULL` string being saved in the password field, and this is checked for by the load routine. Additional fields stored with nickname cores include:
  - `greet`: A greeting message sent from NickServ to the user upon logon. Ignored.
  - `icq`: The user's ICQ number. Ignored.
  Nickname aliases include the same fields as are stored in the `NickInfo` structure. Since nickname cores are stored using the "display name" (main nickname) rather than a separate ID value, `convert-db` first looks up the nickname read from the database, and only creates a new `NickInfo` if the nickname does not already exist.
- `chan.db`: Contains channel data. Additional fields stored with channels include:
  - `forbidby`: The nickname of the user who forbade the channel. Ignored.
  - `forbidreason`: The reason given for the channel forbid. Ignored.
  - `bantype`: Selects among different method of creating a ban mask when banning a user from a channel. Ignored.
  - Several BotServ-related fields, all ignored.
  The major difficulty in importing Epona/Anope channel data is that the meaning of the bitmask values used in the channel mode lock varies depending on the particular IRC server being used. Since this information is not stored in the databases, `convert-db` defaults to only importing the eight basic channel modes, which have consistent flag values across all IRC server types: `+i`, `+k`, `+l`, `+m`, `+n`, `+p`, `+s`, and `+t`. To import other modes, the user must specify the appropriate `-ircd=type` option on the `convert-db` command line; the argument to this option is used to look up an IRC server type (the `IRCD_*` enum defined at the top of the file), which is then used as an index into the `epona_cmode_index[]` array of arrays to process nonstandard mode flag values. Note that there is not a one-to-one correspondence between IRC server type names (taken from the Anope 1.7 protocol module names) and `IRCD_*` constants; protocols using the same mode flag values are combined into a single flag list. (In hindsight, this is probably an unnecessary optimization.)
- `oper.db`: Contains OperServ-related data, both basic data such as maximum user count and lists of autokills and S-lines. Some versions of Epona and Anope also store information about detected proxy hosts, but this data was removed during the development of Anope 1.7 without changing the file version number.
- `exception.db`: Contains session exception data.
- `news.db`: Contains news item data.
- `autoop.db`: Contains nickname auto-op settings. Ignored.
- `bot.db`: Contains data for the Epona/Anope BotServ pseudoclient. Ignored.
- `hosts.db`: Contains data for the Anope 1.5+ HostServ pseudoclient. Ignored.
- `hs_request.db`: Contains data for the Anope 1.5+ HostServ pseudoclient. Ignored.
- `os_info.db`: Contains IRC operator information strings for nicknames and channels (Anope 1.7.9+ only). Ignored.
- `prenick.db`: Contains data on requested but not yet confirmed nicknames in Anope's two-step registration process (Anope 1.5+ only). Since Anope uses an alphanumeric code that cannot be stored in the `NickGroupInfo.authcode` numeric field, this data is currently ignored.

Back to top

#### 9-3-3. `convert-hybserv.c` (HybServ)

HybServ is an IRC service program designed from scratch for networks using the IRCD-Hybrid IRC server. After version 1.6, development changed hands and the program was renamed HybServ2, but as they share a common codebase, "HybServ" is used to refer to both in this documentation. Several modified versions of HybServ have also been seen.

Like Cygnus, HybServ writes its databases to text files. The format is similar to IRC commands, with a record or field identifier followed by an arbitrary number of space-separated parameters, and with a leading colon indicating a parameter that continues to the end of the line (including spaces). The first line of each file begins with "`; Hybserv`", which is used by the `check()` routine to check for the existence of HybServ databases.

HybServ allows passwords to be encrypted, using the Unix `crypt()` function; however, encryption status is not stored in the databases themselves, so the command-line option `-crypt` must be given to `convert-db` to make it treat passwords as encrypted.

- `nick.db`: Contains nickname data. Each nickname record begins with a line that has the nickname itself as the first token on the line; subsequent fields for that record begin with the two characters "`->`" followed by a field name. The fields are:
  `nickname flags time-registered last-seen`
    Begins a new nickname record.
  `->PASS password`
    The nickname's password.
  `->PERMPASS password`
    A "permanent password" for the nickname (only present in some modified versions of HybServ); ignored.
  `->FORBIDBY nickname`
    The nickname of the user who forbade this nick; ignored.
  `->FORBIDREASON reason`
    The reason for the nickname forbid; ignored. (This field is called `FREASON` in some modified versions of HybServ.)
  `->FTIME time`
    The time at which the nickname was forbidden (only present in some modified versions of HybServ); ignored.
  `->EMAIL address`
    E-mail address for the nickname.
  `->URL url`
    URL for the nickname.
  `->GSM string`
  `->PHONE string`
  `->UIN string`
  `->ICQ string`
    Various user information fields for the nickname; ignored. (`ICQ` is only present in some modified versions of HybServ.)
  `->LANG language`
    Believed to identify the language selected by the user (only present in some modified versions of HybServ); ignored due to a lack of data to correlate values with languages.
  `->LASTUH user host`
    The last-seen usermask for the nickname, with user and hostname as separate tokens.
  `->LASTQMSG message`
    The last quit message used by the nickname.
  `->HOST usermask`
    A hostmask (access) entry for the nickname.
  `->LINK master-nick`
    Indicates that this nickname is linked to another, and gives the parent (master) nickname. Master nicknames are always written before the nicknames that link to them.
- `chan.db`: Contains channel data.
  `channel flags time-registered last-used`
    Begins a new channel record.
  `->FNDR nickname`
    The channel founder's nickname.
  `->SUCCESSOR nickname`
    The channel successor's nickname.
  `->PASS password`
    The channel's founder password.
  `->PERMPASS password`
    A "permanent password" for the channel (only present in some modified versions of HybServ); ignored.
  `->ACCESS nickname level`
    An access entry for the channel. Levels are adjusted so that users have close to the same privileges as they did in HybServ (assuming default HybServ privilege settings), but as there is not a one-to-one match between levels and privileges, some users will end up with more or less privileges than they had previously (see under HybServ in section 5-3 of the user's manual).
  `->AKICK mask reason`
    An autokick entry for the channel.
  `->ALVL level...`
    Privilege access levels for the channel (all on one line); ignored.
  `->TOPIC topic`
    Saved topic for the channel. Since the topic setter and time are not saved, they are set to "`<unknown>`" and the current time, respectively, in the XML output.
  `->MON mode-mask`
    Modes locked on for the channel, as a combination of numeric flags.
  `->MOFF mode-mask`
    Modes locked off for the channel, as a combination of numeric flags.
  `->KEY key`
    Locked key for the channel.
  `->LIMIT limit`
    Locked limit for the channel.
  `->FORWARD string`
    Presumed to be a forwarding channel for when the channel reaches its user limit (`+l`), and stored as the channel link parameter accordingly, but as the IRC server with which this is used (Dancer IRCd) appears to be defunct, I am not certain of this interpretation.
  `->ENTRYMSG message`
    Entry message for the channel.
  `->EMAIL address`
    E-mail address for the channel.
  `->URL url`
    URL for the channel.
- `memo.db`: Contains memo data. The data is organized by nickname, with each memo on a single line:
  `nickname`
    Begins a group of memos, and identifies the nickname to which the memos belong.
  `->TEXT sender time flags text`
    Data for a single memo.
- `stat.db`: Contains the following network-wide statistics:
  `->USERS maxusers maxusers-time`
    The maximum number of users seen on the network, and the time at which the maximum was reached. Used to set the corresponding OperServ data.
  `->OPERS maxopers maxopers-time`
    The maximum number of IRC oprators seen on the network, and the time at which the maximum was reached. Ignored.
  `->OPERS maxopers maxopers-time`
    The maximum number of IRC oprators seen on the network, and the time at which the maximum was reached. Ignored.
  `->OPERS maxopers maxopers-time`
    The maximum number of IRC oprators seen on the network, and the time at which the maximum was reached. Ignored.
- `oper.db`: Seems to contain a list of current user modes set on online users. Ignored.
- `ignore.db`: Contains OperServ ignore data. Services does not store this data to disk, so this file is ignored.
- `seen.db`: Data for SeenServ; ignored.

Back to top

#### 9-3-4. `convert-magick.c` (Magick, Wrecked)

Magick IRC Services is an IRC service program based on a very old version of Services, and WreckedNet IRC Services is a modified version of Magick; both seem to be defunct as of the writing of this manual.

The databases used by these programs are similar to the format used by Services before machine-independence was introduced in version 4.0: rather than writing each variable in a consistent way, they simply dump the structures to disk as is. As such, `convert-db` assumes that the databases are being loaded on the same machine that produced them; attempting to read the databases on a different architecture (and in some cases, on the same architecture using a different compiler) will likely fail.

Magick and Wrecked support nickname and channel suspensions via flags, but do not record any other suspension information, so default values are filled in. These programs also support a hierarchical system of nickname links, and these are resolved into nickname groups after all nicknames are read in.

The data files used by Magick and Wrecked are as follows:

- `nick.db`: Contains nickname data.
- `chan.db`: Contains channel data.
- `memo.db`: Contains memo data.
- `news.db`: Contains channel news data; ignored.
- `sop.db`: Contains the Services operator list (Services operators in Magick and Wrecked are equivalent to Services administrators in Services, and are imported as such).
- `akill.db`: Contains autokill data.
- `clone.db`: Contains session exception data.
- `message.db`: Contains network message data (imported as news items).

Back to top

#### 9-3-5. `convert-ptlink.c` (PTlink)

PTlink Services is an IRC service program designed specifically for the PTlink IRC server. It appears to be based on a fairly old version of Services, and uses a similar data file format. (Another, apparently separately developed, program called PTlink IRC Services has recently appeared; it uses MySQL for database storage, and is not supported by `convert-db`.)

PTlink stores the encryption method used for passwords with the corresponding nickname or channel, a significant improvement over Services' method (at the time) of using a single method for the entire database. `convert-db` reads the encryption method and includes it in the XML output; however, the "JP2" method used in PTlink is not available in Services, and any passwords encrypted with this method, or with an unknown method, are reset to the corresponding nick or channel name with no encryption (a warning is printed in this case).

PTlink also stores record counts in the nickname and channel databases, similar to Cygnus, for the purpose of ensuring that the data is loaded correctly; however, there have apparently been bugs in some versions of PTlink that caused valid databases to have a mismatch between this value and the number of records actually recorded. `convert-db` still checks the value, but the warning message on mismatch includes a note about this issue.

The following data files are used by PTlink (some only by more recent versions):

- `nick.db`: Contains nickname and memo data. Suspension status is stored as a flag, without setter, time, or expiration. PTlink stores the following additional data, currently ignored:
  - `icq_number`: ICQ user number, as a string.
  - `location`: User's location.
  - `last_identify`: Last time the nickname was identified for. PTlink updates the "last seen" time regardless of authentication status, and uses this field instead to record use by an authenticated user. To maintain user-interface compatibility, we keep the old last-seen time, even though we treat it differently, rather than use this time.
  - `last_email_request`: Last time the `SET EMAIL` command was used. Services only records this in memory, not on disk.
  - `birth_date`: Presumably intended to allow the user to record their birth date (stored as a numeric time value), but this field appears to be unused in recent versions of PTlink.
  - `news_mask`: NewsServ-related options.
  - `news_status`: Presumably NewsServ-related, but appears to be unused in recent versions of PTlink.
  - `notes`: These seem to be a sort of memo-to-self feature; they could potentially be imported as memos.
  As of data file version 10, PTlink did away with the legacy zero byte used to terminate a record chain for a single hash table entry, simply storing a sequence of records.
- `chan.db`: Contains channel data. This file does not have a version 10, and the hash chain terminator bytes are always present; the hash table size was increased from 256 to 65536 in data file version 9. PTlink stores the following additional data, currently ignored:
  - `maxusers`: Maximum number of users seen on the channel.
  - `maxtime`: Time when the maximum number of users on the channel was reached.
  - `drop_time`: Time when the channel was dropped with a DROP command. Only present if the 0x1000 (`CI_DROPPED`) flag is set. Used by the PTlink "delayed drop" system.
  - `memos`: PTlink supports channel memos (like old versions of Services), which are discarded.
- `oper.db`: Contains the list of Services administrators and operators, and the network-wide maximum user count and time of maximum.
- `akill.db`: Contains autokill data.
- `sqline.db`: Contains SQline data.
- `sxline.db`: Contains SXline data (what Services calls SGlines).
- `news.db`: Contains news data.
- `newsserv.db`: Contains NewsServ data; ignored.
- `bots.db`: Contains bot data; ignored.
- `vline.db`: Contains SVline data (S-lines for blocking certain DCC filenames); ignored.
- `vlink.db`: Contains VLINK data (a feature in recent versions of the PTlink IRC server); ignored.

Back to top

#### 9-3-6. `convert-sirv.c` (Sirv, Auspice, Bolivia)

SirvNET Services is an IRC service program designed for use on SirvNET. Earlier versions were based on an old version of Services; version 3.0.0 was a complete rewrite, and development is actively continuing. Since version 3.0.0, Sirv requires a MySQL database to operate, and apparently has no way to export its data to ordinary files; thus, Sirv databases are only supported through version 2.9.0.

Auspice is an IRC service program that appears to have been based on an old version of Sirv, and was designed for UnrealIRCd networks. Development status is unclear.

Bolivia IRC Services is an IRC service program that also appears to have been based on Sirv, and developed for a particular network. The program appears to be defunct as of the writing of this manual.

All three of these programs share the same overall file format, so they have been grouped in the same file despite fairly significant differences in the details to avoid code repetition. The base format seems to be that from Services 3.x, before machine-independence was introduced.

The database files are as follows:

- `nick.db`: Nickname data. All three programs share a common base nickname data structure (the `oldni` variable), and each has its own additions to the structure. (As a side note, Bolivia's extra data structure, consisting entirely of padding, is not written to disk due to a missing comment terminator in the structure definition.) The common load routine then loads string data for the appropriate database type and initializes NickInfo and NickGroupInfo structures for the loaded data. Bolivia has a flag for nickname suspensions, and if it is set, dummy suspension data is created for the nickname group. Auspice has a nick linking system, similar to the hierarchical system introduced in Services 4.0, indicated by a nickname flag; if the flag is set, the `last_usermask` field contains the parent nickname. These links are resolved into nickname groups after all nicknames have been loaded.
- `chan.db`: Channel data. As with the nickname database, all three programs share a common base structure—with the exception of mode lock data, which is stored as `short` numeric values in Sirv and Bolivia but 64-byte string buffers in Auspice. The routine first reads the initial part of the common structure (`oldci`), then reads either two shorts or two 64-byte buffers for the mode lock data, then reads the latter part of the common structure (`oldci2`). This can theoretically cause alignment problems due to the mode lock variables not being part of the structure, but no such problems have yet been reported. The Sirv and Bolivia formats are similar, but Auspice also includes:
  - Channel successors.
  - A record of who added a channel access entry (also present in recent versions of Sirv).
  - `TIMEOP` entries on the access list: users who only get channel operator privileges at certain times. These are discarded.
  - Channel news data.
  - Channel "bad word" data.
- `memo.db`: Memo data. All three programs use the same format here, with the exception that Auspice has a flag for marking memos to be saved; this flag is used (inverted) to set the "may expire" flag in imported memos.
- `os_sop.db` (Sirv only): Services operator list. Consists of a count followed by a list of strings.
- `os_sa.db` (Sirv only): Services administrator list. Consists of a count followed by a list of strings.
- `admin.db` (Auspice only): Services administrator/operator list. Stored like the nickname and channel databases, with a series of entries each preceded by a nonzero byte, followed by a zero byte, for each hash table entry. Auspice keeps a fair amount of information for each record in this table, but since Services does not record such information, only the status flag is used to set the nickname's OperServ privilege level (`ngi->os_priv`).
- `akill.db`: Autokill list. All three programs share the same straightforward format.
- `trigger.db`: Trigger (session exception) list. All three programs share the same straightforward format.
- `gline.db`, `qline.db`, `zline.db` (Bolivia only): S-line data. These files use simple arrays of strings preceded by a count.

Back to top

#### 9-3-7. `convert-trircd.c` (trircd)

trircd IRC Services is a fork of Services 4.5.36 developed for the tr-ircd IRC server, and has been discontinued since support for tr-ircd was added to Services. The data files are essentially the same as those in Services 4.5.36, with the addition of the following data files:

- `ajoin.db`: Nickname-related extension data for each registered nickname, including:
  - Autojoin list.
  - Forbidder nickname and reason for forbidden nicknames.
  - E-mail address authentication status.
  - Memo ignore list.
  - Nickname information string.
  - Memo expiration data (ignored).
- `cforbid.db`: Channel-related extension data for each registered channel, including:
  - Forbidder nickname and reason for forbidden channels.
  - Time added, last used time, and expiration time for autokick entries (expiration times are not supported for autokicks and are ignored).
  - Last used time for access entries (ignored).
- `exclude.db`: Autokill exclusion data, stored in the same format as autokill data.
- `sgline.db`, `sqline.db`, `szline.db`: S-line data, stored in the same format as autokill data.

Back to top

#### 9-3-8. `convert-ver8.c` (Daylight, IRCS)

Daylight is a fork of Services 4.3.3 developed for the UnrealIRCd IRC server, and has been discontinued since support for Unreal was added to Services. IRCS is a fork of Services 4.0.5 developed for Undernet (ircu) IRC servers, and appears to be defunct as of the writing of this manual. Both use a data format essentially unchanged from that in the original Services versions; the data file format at that time was version 8, hence the source file name "`convert-ver8.c`".

The Daylight database format is almost completely unchanged from the original version 8, with the exception of an extra channel flag `CI_XMANAGEMENT` which is ignored.

The IRCS database format uses a channel name buffer size of 204 bytes and a password size of 16 bytes. Services defaults to a maximum channel name buffer size of 64 bytes, and will truncate (with a warning) any channel name that is too long to fit in the buffer. IRCS also uses five OperServ privilege levels instead of two, and users on the extra lists ("senior", "junior", and "helper") are moved onto either the admin or the oper list depending on appropriate privileges.

IRCS adds one data file to the base Services set: `gline.db`, containing "G-line" (autokill) data.

Back to top

Previous section: Other modules | Table of Contents | Next section: Compilation