Instructions for installing 3rd party UnrealIRCd modules

These installation instructions were written specifically for the use with my modules. They may work with ones from other authors as well, but, for example, some modules might require additional steps.

List of contents:

  1. Module installation on *NIX
  2. Module installation on Windows (with UnrealIRCd 3.2.1 and newer versions)
  3. Module installation on Windows (with UnrealIRCd 3.2 and older versions)
  4. Appendix: Compiling Unreal on win32 with remote includes support

1. Module installation on *NIX:

To install modules on *NIX, you must compile their sources with the UnrealIRCd source package. If you want only modules to compile, you can skip steps 1, 4 and 5. As soon as you installed your ircd and it's running, additional modules can be compiled and loaded without the necessity of restarting your server, a simple /rehash is enough  (except if you want to reload/remove a module doesn't allow itself to be unloaded).

Step 1:
 Download the Unreal3.2 source and extract it to a preferred directory.
Step 2:
 Download the modules you wish to install. If a module is compressed in a tar.gz file, then first you have to unpack it with the "tar -zxvf file.tar.gz" shell command, or with this one: "gunzip < file.tar.gz | tar xvf -". If the extraction fails, probably the file is damaged, then you can use my MD5 sum files to find it out.

After that, copy those files with '.c' extension to Unreal3.2/src/modules.
Step 3:
 Change directory (back) to Unreal3.2/.
Step 4:
 Type "./Config".
Step 5:
 Type "make" (or "gmake" if the previous one is not the GNU version of the 'make' utility).
Step 6:
 Each module is compiled one by one. So to compile one, type "make custommodule MODULEFILE=<modulename>" where <modulename> is the filename of a module without extension.

Examples:
make custommodule MODULEFILE=m_getinfo
make custommodule MODULEFILE=jointhrottle
Step 7:
 Optionally, you can run "make install" (only if you configured a non-default installation directory)
Step 8:
 Now tell ircd to load the modules (either on startup or when rehashing configuration). You have to add a loadmodule directive in your configuration file (unrealircd.conf) for each modules like this:

loadmodule "src/modules/modulename.so";

Where "modulename" is the name of the module file (without extension). If the path is wrong (for example, if you have run "make install", then the right path is probably "modules/modulename.so"), correct it properly.

If you don't like compiling modules by hand, you can also try my module installer script.

Note: Once the modules have been installed and you're going to upgrade your ircd, don't forget to reinstall the module files too! Old .so files usually don't work with new ircd compilations, or may result in strange malfunctions. A frequent problem with mixed versions of binaries is, when you get an "unresolved symbol" error message at the time you load a module. That's why a full recompilation is  always necessary.

2. Module installation on Windows (with UnrealIRCd 3.2.1 and newer versions):

Since 10th June 2004, UnrealIRCd has full Windows module support. This lets you be able to use pre-compiled DLL files and load them very easily. However, because of the fact I don't have a win32 C++ compiler  (as I don't have Windows either), I can't provide DLL files for my modules. Fortunately I've got some help from a few people (lots of thanks) who can generate those files and make them available for you. The download locations can be found at the modules page.

In case you'ld like to compile a module from its source, http://www.vulnscan.org/unrealwin32dev/ contains lots of useful information for you. You can also download a package of pre-compiled libraries there (zip, ssl, curl and c-ares), which can be used with UnrealIRCd.

2.1. Notes on compatibility issues

DLL files are incompatible with different Unreal versions. You shouldn't use a DLL that was not compiled for the version you have. Old .dll files usually don't work with new ircd compilations, or may result in strange malfunctions. A frequent problem with mixed versions of binaries is, when you get an "unresolved symbol" error message at the time you load a module.

Additionally, it's good to know that SSL and non-SSL module compilations are compatible with Unreal: no matter if the wircd has SSL support or not, the modules will work, you will only notice that a non-SSL module lacks the SSL features if it's used with an SSL-enabled UnrealIRCd (while there will be no problems at all if the module has SSL support).

However there's no such win32 binary compatibility for zip/non-zip modules. There will be in Unreal3.2.2, but until it isn't released, you should make sure you are using the correct compilation, or you may experience frequent crashes.

2.2. Installlation methods

Choose your way of installation:
As soon as you installed your ircd and it's running, additional modules can be compiled and loaded without the necessity of restarting your server, a simple /rehash is enough  (except if you want to reload/remove a module doesn't allow itself to be unloaded).

 The following information originally comes from codemastr (I made some changes however), as I don't have too much knowledge how compiling goes under win32. If you have a question about it, I suggest you to ask any of the  Unreal developers, but please not me. :) [However, don't forget to read Unreal3.2/doc/compiling_win32.txt before disturbing them!] Certainly, I'll try to keep these information updated as much as I can.

You would need MS Visual C/C++ 6.x with the SDK platform, or MS Visual C/C++ 7.x.

Step 1:
 Download the Unreal CVS source files and extract them.
Step 2:
 Run the SDK platform for your OS.
MSVC 6.0:
start -> programs -> platform sdk blabla -> open build env. -> choose os) -> set blabla build env (debug). This will launch a DOS window.

MSVC 7.x:
Start the Visual Studio .NET Command Prompt
Step 3:
 Go to the Unreal source directory.
Step 4:
 Compile the Unreal source by typing:

nmake -f makefile.win32
Step 5:
 If you are using Unreal3.2.1 with zip links support, type:
nmake -f makefile.win32 USE_ZIPLINKS=1 ZLIB_INC_DIR="c:\dev\zlib" ZLIB_LIB_DIR="c:\dev\zlib\dll32" custommodule MODULEFILE=<modulename>

(The whole command is one line. Obviously, '<modulename>' should be replaced with the name of a module file without extension, for example with 'm_getinfo' or 'jointhrottle'. Also modify the path of the ZLIB include and library paths, if necessary.)

If you are using Unreal3.2.2 or newer, or you don't want zip links support, type:
nmake -f makefile.win32 custommodule MODULEFILE=<modulename>

(where '<modulename>' has the same meaning as above).

This should give u a DLL.
Step 6:
 Copy the DLL to ur modules folder.
Step 7:
 loadmodule module_folder\your_module.dll;

If you get an error message like "The specified module could not be found" or "One of the library files needed to run this application cannot be found", please read section 2.3, below.

2.3. Library requirements

Every software that is compiled with some version of Microsoft Visual Studio requires an MSVCRT (Microsoft Visual C++ Runtime) library of the same version. For example, the official win32 port of Unreal3.2.1b was compiled with Visual Studio 7.0 (I call it VS henceforth), and requires msvcr70.dll. That file is automatically downloaded at the time you install Unreal, so you don't need to worry about.

However, 3rd party modules that were compiled with a different version of VS may require an other additional CRT library. So when you are trying to load a module and you get an error message like "The specified module could not be found", it isn't because you specified a wrong path (otherwise the message would be "no such file or directory" or something similar), it is because of the additional library requirement that Microsoft simply calls as a module. A much better version of the same error message sounds like this: "One of the library files needed to run this application cannot be found", however they all might be translated to your language.

Below I'm giving you a list of VS versions and their library requirements:

VS 6.0
 msvcrtd.dll (or if not the debug version, msvcrt.dll)
VS 7.0 (.NET)
 msvcr70.dll (comes with Unreal)
VS 7.1 (.NET)
 msvcr71.dll

Copy the necessary DLL to one of the default search locations (for example, either to the same directory where wircd.exe is located, or the System directory of Windows).

3. Module installation on Windows (with UnrealIRCd 3.2 and older versions):

This is an old, obsolete way of module compilation and shouldn't be used in the future. It's suggested to always use the latest version of UnrealIRCd. With these older versions the only way to load a modules is to modify the UnrealIRCd source code, so you can compile/link them statically. (That means the modules won't be loadable and unloadable at runtime, of course.) And you don't want to lose support, do you?

Now that you are aware of this, and you know what the consequences of using an old version are, here are the instructions how to compile modules. The following description was originally written by |VIO|Maverick (lots of thanks for his time and work for helping me).

*Note: a Microsoft Visual C++ compiler program and the source code of UnrealIRCd 3.2 are required minimally [the "Unreal3.2-RCx (Win32)" and "(Win32-SSL)" versions are called binaries and they are unusable for compilation]. Without them the compilation steps below are pointless. Don't question me about compilation, because I can't answer; you can find a short description in Unreal3.2/doc/compiling_win32.txt instead.

Step 1:
 Download the Unreal3.2 source and the modules you wish to add, unpack them and place the module files (with .c extension) in src/modules/. (If the extraction of a module fails, probably the tar.gz file is damaged, then you can use my MD5 sum files to find it out.)
Step 2:
 Open makefile.win32 for editing, go to the user configuration section and follow the instructions. Keep the file open for further editing.
Step 3:
 Now look for the section that starts with:

MOD_FILES=

It will be a section like this:

MOD_FILES=SRC/L_COMMANDS.OBJ SRC/M_CHGHOST.OBJ SRC/M_SDESC.OBJ SRC/M_SETIDENT.OBJ \
 SRC/M_SETNAME.OBJ SRC/M_SETHOST.OBJ SRC/M_CHGIDENT.OBJ SRC/M_SVSMOTD.OBJ \
 SRC/M_SVSNLINE.OBJ SRC/M_WHO.OBJ SRC/M_SWHOIS.OBJ SRC/M_SVSMODE.OBJ \
 SRC/M_AWAY.OBJ SRC/M_SVSNOOP.OBJ SRC/M_MKPASSWD.OBJ SRC/M_SVSO.OBJ SRC/M_SVSNICK.OBJ \
 SRC/M_ADMINCHAT.OBJ SRC/M_AKILL.OBJ SRC/M_CHGNAME.OBJ SRC/M_GUEST.OBJ SRC/M_HTM.OBJ \
 SRC/M_LAG.OBJ SRC/M_MESSAGE.OBJ SRC/M_NACHAT.OBJ SRC/M_OPER.OBJ \
 SRC/M_PINGPONG.OBJ SRC/M_QUIT.OBJ SRC/M_RAKILL.OBJ SRC/M_RPING.OBJ SRC/M_SENDUMODE.OBJ \
 SRC/M_SQLINE.OBJ SRC/M_KILL.OBJ SRC/M_TSCTL.OBJ SRC/M_UNKLINE.OBJ \
 SRC/M_UNSQLINE.OBJ SRC/M_UNZLINE.OBJ SRC/M_WHOIS.OBJ \
 SRC/M_TKL.OBJ SRC/M_VHOST.OBJ \
 SRC/M_CYCLE.OBJ SRC/M_SVSJOIN.OBJ SRC/M_SVSPART.OBJ SRC/M_SVSLUSERS.OBJ \
 SRC/M_SVSWATCH.OBJ SRC/M_SVSSILENCE.OBJ SRC/M_SENDSNO.OBJ SRC/M_SVSSNO.OBJ

To add a module, you must first add a "\" at the end of the last line. For example, change

  SRC/M_SVSWATCH.OBJ SRC/M_SVSSILENCE.OBJ SRC/M_SENDSNO.OBJ SRC/M_SVSSNO.OBJ

to

  SRC/M_SVSWATCH.OBJ SRC/M_SVSSILENCE.OBJ SRC/M_SENDSNO.OBJ SRC/M_SVSSNO.OBJ \

Now you can start adding your modules by adding a line with the path name to the .obj file. The .obj file is the same filename as your .c file with the .c changed to .obj and the pathname is always src/ and it is all in caps. Example:

SRC/MODULENAME.OBJ

*Note: If you have more than one module, you can add more than one per line, however I only do two per line, but you can do more if you like...

For each line you add unless it is the last line, you must add a "\" at the end like I told you above. Example:

SRC/MODULENAME.OBJ SRC/MODULENAME2.OBJ SRC/MODULENAME3.OBJ \
SRC/MODULENAME4.OBJ SRC/MODULENAME5.OBJ
Step 4:
 Go towards the bottom of the file and look for the part that has

src/m_svssno.obj: src/modules/m_svssno.c $(INCLUDES)
$(CC) $(CFLAGS) src/modules/m_svssno.c

Here is where you start adding your new modules. Add them in the same format as above, put a blank line between the previous entry and your new one. Example:

src/m_svssno.obj: src/modules/m_svssno.c $(INCLUDES)
$(CC) $(CFLAGS) src/modules/m_svssno.c

src/modulename.obj: src/modules/modulename.c $(INCLUDES)
$(CC) $(CFLAGS) src/modules/modulename.c

src/modulename2.obj: src/modules/modulename2.c $(INCLUDES)
$(CC) $(CFLAGS) src/modules/modulename2.c

*Note: notice the first filename has a .obj, the other two is the name of your .c file for each section.

Now you can save and close your file and proceed to the next step.
Step 5:
 This is where it gets interesting for you new guys! :) Before moving on this step, you must know a thing about modules: all of them have general functions, one for testing (<modulename>_Test), one for initializing (<modulename>_Init), one for loading (<modulename>_Load) and one for unloading (<modulename>_Unload). The testing function may not appear in all modules, therefore you have to find out whether the actual module you are compiling has it or not. Don't worry, it's not difficult! For example, when you see the following line in a module file:

DLLFUNC int MOD_TEST(modulename)(ModuleInfo *modinfo)

then you can be sure the module has a testing function.

Open src/modules/l_commands.c for editing.

This step has to be done only on those modules that have a testing function. Find the area that has the lines like the one below and start a new line at the end of the section:

extern int m_htm_Test(ModuleInfo *modinfo);

Now you add a line just like the one above it with a few changes. Example:

extern int modulename_Test(ModuleInfo *modinfo);

Or you can add two or more modulenames in a line (only two is recommended). Example:

extern int modulename_Test(ModuleInfo *modinfo), modulename2_Test(ModuleInfo *modinfo);

*Note: notice the modulename at the first does not have a filename extension, yet the first part is the name of the file modulename with _Init after it with no space. There are 2 modules in this line, the second one is separated by a comma and a space and you MUST add the ending ";" for each line.
Step 6:
 Find the area that has the lines like the one below and start a new line at the end of the section:

extern int m_sendsno_Init(ModuleInfo *modinfo), m_svssno_Init(ModuleInfo *modinfo);

Make sure your new line goes before:
 
#ifdef GUEST
extern int m_guest_Init(ModuleInfo *modinfo);
#endif

Now you add a line just like the one above it with a few changes. Example:

extern int modulename_Init(ModuleInfo *modinfo);

Or you can add two or more modulenames in a line (only two is recommended). Example:

extern int modulename_Init(ModuleInfo *modinfo), modulename2_Init(ModuleInfo *modinfo);

*Note: notice the modulename at the first does not have a filename extension, yet the first part is the name of the file modulename with _Init after it with no space. There are 2 modules in this line, the second one is separated by a comma and a space and you MUST add the ending ";" for each line.
Step 7:
 Find the next block of text with lines like

extern int m_sendsno_Load(int module_load), m_svssno_Load(int module_load);

Now add your new line. Same rules as before, separated by a comma and a space, and don't forget the ending semicolon.

extern int modulename_Load(int module_load), modulename2_Load(int module_load);
Step 8:
 Find the next block of text with lines like

extern int m_sendsno_Unload(), m_svssno_Unload();

Now add your new line. Same rules as before, separated by comma and space, don't forget the ending semicolon.

extern int modulename_Unload(), modulename2_Unload();
Step 9:
 OK. We are ready with telling the program what new functions we have, now let's use them.

This step has to be done only on those modules that have a testing function.
Find the section that has the following line:

m_htm_Test(ModCmdsInfo);

Now add your new lines like the one above, same rules as before, but only one module per line with ending semicolon. Example:

modulename_Test(ModCmdsInfo);
modulename2_Test(ModCmdsInfo);
modulename3_Test(ModCmdsInfo);
Step 10:
 Find the end of the section that has lines like

m_svssno_Init(ModCmdsInfo);

Now add your new lines like the one above, same rules as before, but only one module per line with ending semicolon. Example:

modulename_Init(ModCmdsInfo);
modulename2_Init(ModCmdsInfo);
modulename3_Init(ModCmdsInfo);
Step 11:
 Find the end of the section that has lines like

m_svssno_Load(module_load);

Now add your new lines like the one above, same rules as before, but only one module per line with ending semicolon.

modulename_Load(module_load);
modulename2_Load(module_load);
modulename3_Load(module_load);
Step 12:
 W00T!!! This is the LAST editing step......

Find the end of the section that has the lines like

m_svssno_Unload();

Now add your new lines like the one above, same rules as before, but only one module per line with ending semicolon.

modulename_Unload();
modulename2_Unload();
modulename3_Unload();

Now save and close your file.
Step 13:
 Refer to the Unreal3.2/doc/compiling_win32.txt document to complete the compilation.

4. Appendix: Compiling Unreal on win32 with remote includes support

The following instructions were written by fez (thank you!), I've made only little modifications on the original text. Should help a lot if you want to compile UnrealIRCd with libcurl/c-ares enabled.

Note: there's an official documentation on this, which isn't included with the Unreal3.2.1 package. I'm planning to remove this section after Unreal3.2.2 gets released.

Just in case you're ever interested in compiling unreal on win32 with libcurl, you should know that NO ONE maintains the libcurl win32 branch anymore.

To get it to work you have to do several things:

Step 1:
 get c-ares,
Step 2:
 open the .dsp in the vc/areslib dir, convert the .dsp to .sln
Step 3:
 remove the file ares_freemem.c or whatever its called from the project
Step 4:
 change the default library to single threaded (i think you only have to do that on Release build)
Step 5:
 compile c-ares

Step 6:
 get libcurl
Step 7:
 open the .dsp in the lib dir, convert it to .sln
Step 8
 add the files ares_cancel.c and ares_version.c from the c-ares dir to the project
Step 9
 edit include/curl/multi.h from the curl dir and change #include <winsock2.h> to #include <winsock.h>
Step 10: edit lib/config-win32.h from the curl dir and add #define USE_ARES 1
Step 11: change the default library to single threaded (for both release and debug builds)
Step 12: add /I "path-to-c-ares-includes" to the c/c++ command-line in project properties
Step 13: add /LIBPATH:"path-to-c-ares-library" areslib.lib /DEF:libcurl.def to the LINK command-line in project properties
Step 14: compile libcurl

Now you should have the correct libcurl.dll and libcurl.lib with which to compile Unrealircd.