14 October 2003
Frank Seesink
http://frank.seesink.com/jabber

Contents:

	- Disclaimer
	- Comments About Building *nix Apps Under Cygwin
	- Example File
	- Steps for Building Jabberd Under Cygwin
		- includes building modules JUD, MU-Conference,...
	- Advanced Settings
		- includes running Jabberd as NT service
	- Final Comments

----------------------------------------------------------------------

The current version of this document can be found on
http://jabberd.jabberstudio.org/1.4/doc/winguide

______________________________________________________________________
DISCLAIMER

This information is provided "as is", with no warranty, expressed or 
implied, of any kind blah blah blah.  It's open source.
You know the drill. :-)

Please note all testing was done under Windows 2000/XP, and as such, I 
make no claims as to the functionality of Jabberd under Cygwin when run on 
Windows 9x/Me.  All example files/scripts/etc. work with the assumption 
that you have decompressed the Jabberd source code into

	/usr/local/jabber

(i.e., configure, jabber.xml, can be found in this directory) and that
this is the directory from which you will be running your jabber server.

Also, note that while I have been able to make Jabberd run smoothly, your 
mileage may vary.  One issue I DO see is that you cannot run Jabberd in 
debug mode (i.e., ./jabberd/jabberd.exe -D), as this will cause the server 
to segfault.  However, avoid debug mode, and all appears well.  I am still 
trying to determine why (though indications are, once again, that Pth is 
involved, which makes me suspect another fork()ing issue.)
 
______________________________________________________________________
COMMENTS ABOUT BUILDING *NIX APPS UNDER CYGWIN

With the modifications made since Jabberd v1.4.2, you should now be able
to build Jabberd under Cygwin just as you would under *nix, with a few 
exceptions.  For those interested, note that building *nix applications
under Cygwin tends to run into problems in the following areas:

	* dynamic libraries
	* DNS (Domain Name System) resolution/functionality
	* the use of fork()

Unfortunately, Jabberd touches on ALL of these capabilities to some 
extent.

Dynamic libraries are an OS-specific feature, requiring the OS to play its
role in loading/unloading libraries.  In *nix, dynamic libraries have
filenames ending in .so, whereas in Windows they end in .dll.  This is 
more cosmetic in nature, but it requires changing all modules such as JUD 
or MU-Conference so that their filenames end in .dll (see setup.sh).

More importantly, however, is the fact that *nix and Windows compile their 
libraries differently, and in order to make a *nix library build/work 
under Cygwin, it requires using certain Cygwin tools to build a list of 
EXPORTed functions/variables and then building the libraries as Windows 
would expect.  See the various Makefiles for details on the commands used 
under Cygwin vs. typical *nix builds.  Basically it involves building an 
EXPORT list via 'nm' and then building the libary using 'dllwrap'.

DNS is another area where compiling *nix apps under Cygwin falls down 
hard.  In *nix, you can expect to find BIND (Berkeley Internet Name 
Domain) or something like it.  This provides you not only with a DNS 
server, but also as a programmer with all the functions you might 
need for DNS resolution, via libraries like libresolv 
(/usr/lib/libresolv.a) and their matching header files like
/usr/include/resolv.h, /usr/include/arpa/nameser.h, etc.

Unfortunately, BIND does not build cleanly under Cygwin (so far one can 
only Google for hacks), and there is no BIND package available via 
Cygwin's setup.exe.  This means that as a programmer, you do not get the 
header files or necessary libraries for doing DNS functions.  Since 
Jabberd does DNS resolution for its 'dialback' feature, this required a 
rewrite of that portion of Jabberd for Cygwin.  This is the ugliest part 
of the Cygwin build, as you will find setup.sh simply overwrites the 
standard ./dnsrv subdirectory with the Cygwin-specific version.  Thanks go 
to whoever did this rewrite, however, as it does work.

Recently I found a handy utility called 'minires' (v0.9.7 as I write 
this) which implements the more common BIND libresolv functions, allowing 
you to build against it as if you had libresolv.  Unfortunately, in my tests, 
compilation and linking against minires went fine, but attempts to run the 
DNSRV portion (dnsrv.dll) of Jabberd blew up, kicking up rather nasty 
errors.  Though it did not die, it did not do DNS resolution either.  So 
for now, we'll stick to the rewrite from Jabberd v1.4.2.

Finally, fork().  Cygwin is fork()ing hell (pun intended) compared to a 
proper *nix environment.  Applications which use fork() either directly or 
indirectly--as Jabberd does since it uses GNU Pth, which in turn uses 
fork()--often have difficulty under Cygwin.  As mentioned above, when 
attempting to run a version of Jabberd compiled against minires (basically
attempting to build Jabberd under Cygwin as you would do under *nix), I ran
into trouble.  The trouble involved fork().  I do not have a resolution at
this time.

______________________________________________________________________
EXAMPLE FILE

Included is an example configuration file called jabber.xml.example, which 
contains the configuration for a Jabber server run by a fictitious 
organization.  It is provided solely as one example of how you might 
configure a Jabber server.

The configuration assumes the following information:

* The Jabber server will run under Cygwin on a Windows box with
  IP address 192.168.1.100.
* The organization will have DNS entries for the following names, which
  will all resolve to 192.168.1.100:

	           jabber-example.org
	conference.jabber-example.org
	       jud.jabber-example.org

* The Jabber server will run the MU-Conference and JUD components within
  the Jabberd process (as opposed to running them as external/separate
  instances).
* The Jabber server will NOT allow users to register new accounts.
* The Jabber server will ONLY allow users to connect with SSL connections.
  (This is achieved by having the Jabber server only listen to port 5222
  on the loopback address.]
* The Jabber server will allow server-to-server (s2s) communication.
* The Jabber server is located in /usr/local/jabber, with all the usual
  directory structures.  The one exception is that logs will be stored in
  /usr/local/jabber/logs.
* No PID file will be generated, as the Jabber server will be configured
  and run as an NT service, which should avoid issues of multiple
  instances being allowed to fire up.
 
______________________________________________________________________
STEPS FOR BUILDING JABBERD UNDER CYGWIN

The following are the general steps taken to build a working Jabber server
under Cygwin, complete with the following features:

	* SSL support
	* MU-Conference support (v0.3, as v0.5.2 causes causes segfault)
	* JUD support (v0.5)
	* xdb_ldap support         [untested]
	* xdb_sql support (v1.3)   [compiles but untested]
		NOTE:  This builds with PostgreSQL support.
	* running as an NT service

Note all instructions include versions available at the time of this 
writing.

	______________________________________________________________
	 1.  DOWNLOAD FILES

	This includes jabberd, MU-Conference v0.3, JUD v0.5, xdb_ldap,
	and xdb_sql.  Usually these files are in tar.gz format.  For
	the following steps, we will assume the files are in /tmp.
	For those relatively new to Cygwin, download the files via your
	preferred Web browser, then copy the files into C:\cygwin\tmp
	(assuming standard Cygwin install).  Do NOT attempt to decompress
	these files from Windows using WinZip or the like.  When working
	with Cygwin apps, it is always best to do everything within the
	Cygwin world.

	______________________________________________________________
	 2.  DECOMPRESS FILES INTO PROPER LOCATION

	The end result is to have the following directory structure in
	Cygwin:

	/usr/local/jabber
	          +---/jud
	          +---/mu-conference
	          +---/xdb_ldap
	          +---/xdb_sql

	Assuming all the tar.gz files are in /tmp, run the Cygwin BASH
	shell and execute commands something like the following (skip
	steps for any module you have no interest in):

		cd /tmp
		gzip -d *.gz
		cd /usr/local
		tar xvf /tmp/jabberd-1.4.2.tar
		mv jabberd-1.4.2/ jabber/

		#For Jabber User Directory (JUD) support...
		tar xvf /tmp/jud-0.5
		mv jud-0.4/ jud/

		#For MU-Conference support...
		tar xvf /tmp/mu-conference-0.3
		mv mu-conference-0.3/ mu-conference/

		#For XDB_LDAP support...
		tar xvf /tmp/xdb_ldap-1.0.tar

		#For XDB_SQL support...
		tar xvf /tmp/xdb_sql-1.3.tar

	At this point, you will do everything from the BASH shell unless
	otherwise told.

	______________________________________________________________
	 3.  CHECK IF GNU PTH IS INSTALLED

	Jabberd requires the use of GNU Pth (Portable Threads), which
	can be found in ./jabberd/pth-1.4.0/.  [NOTE:  GNU Pth v1.4.0
	was required with Jabberd v1.4.2, but not sure if that's still
	true.  Latest version as of this writing is v2.0.0.]

	To see what version, if any, of GNU Pth is installed, type

		pth-config --version

	______________________________________________________________
	 4.  BUILD/TEST/INSTALL GNU PTH IF NOT INSTALLED

	If in step #3 you did NOT receive an appropriate response, odds
	are you do not have GNU Pth installed.  In this case, it is best
	to compile/test/install GNU Pth before continuing to build 
	Jabberd itself.  Assuming GNU Pth v1.4.0 is still included,
	type the following:

		cd /usr/local/jabber/jabberd/pth-1.4.0
		./configure
		make
		make test
		make install

	Check to make sure the permissions are set right in /usr/local/bin,
	where pth-config is installed, by typing

		ls -al /usr/local/bin

	You should see a line similar to

	-rwxr-xr-x    1 Admin    None         3908 Oct 13 18:00 pth-config

	When you have trouble in Cygwin, always double-check the permissions
	of directories like /bin, /usr/bin, and /usr/local/bin, as often
	you will find the trouble is that an executable has not been set
	properly.

	If all goes well, when you retry the command from step #3,
	you should get a proper response now.

	______________________________________________________________
	 5.  BUILD JABBERD

	At this point you are ready to configure/build Jabberd itself.
	Again, assuming you want SSL support (and have installed OpenSSL
	using Cygwin setup.exe),

		cd /usr/local/jabber
		./configure --enable-ssl
		make

	Assuming no errors, at this point you have compiled your Jabber
	server!  Due to the rewritten DNSRV portion of code, there is one
	additional step you must do under Cygwin (IMPORTANT!):

		cp /usr/local/jabber/dnsrv/jabadns.exe /usr/local/bin/

	This copies the jabadns.exe to /usr/local/bin.  Again check the
	permissions of that directory to make sure you can execute jabadns.
	[A quick check is to simply type 'jabadns' and hit [ENTER].  You
	should get a line similar to

		Syntax: jabadns <read handle> <write handle><debug flag>

	______________________________________________________________
	 6.  TEST JABBERD

	At this point, you should have a working Jabber server.  If you like,
	you can start testing using the included jabber.xml file, firing up the
	server with

		./jabberd/jabberd.exe

	and following the Admin Guide steps for testing an initial Jabber
	server.

	WARNING:  Unfortunately, Cygwin is technically an unsupported
	          platform, so if you run into difficulty, please be aware
	          that help may be limited.

	When ready, continue building the modules with the steps below.
	The steps for building modules is pretty straightfoward, assuming
	the Makefile changes I introduced were either incorporated in the
	modules themselves or are available here in ./cygwin.  If
	a module does not build properly, there is a very good chance that
	you are working with an unmodified version (i.e., module source
	code that does not include the nessary modifications to its
	Makefile).  As of this writing, I do not know what changes will
	be included with Jabberd itself, which will have to be incorporated
	by the module writers, and which you may have to download and
	plug in yourselves.  Apologies in advance for any confusion.

	The following steps assume you have already decompressed the
	necessary files into /usr/local/jabber/....

	______________________________________________________________
	 7.  BUILD JUD

		cd /usr/local/jabber/jud
		make

	______________________________________________________________
	 8.  BUILD MU-CONFERENCE (v0.3)

		cd /usr/local/jabber/mu-conference/src
		make

	______________________________________________________________
	 9.  BUILD XDB_LDAP

	As of this writing, OpenLDAP (slapd) is NOT available as a Cygwin
	package, meaning you will have to build from source and have
	OpenLDAP working prior to attempting this build.  This build relies
	on files installed by OpenLDAP (e.g., #include <ldap.h>), and as
	such, I have not tested even the compile at this point (though I 
	suspect it will build just fine with all the appropriate 
	headers/libs in place).

		cd /usr/local/jabber/xdb_ldap/src
		make

	______________________________________________________________
	10.  BUILD XDB_SQL

	Be sure to read through the documentation that comes with XDB_SQL
	prior to attempting a build.  Though the build portion is rather
	straightforward, you may wish to tune your configuration for the
	particular database engine you will be using.  Note you must adjust
	the Makefile for the particular dbms you will be connecting with
	(e.g., MySQL, ODBC, PostgreSQL, etc.) before building.

	WARNING!  If my Makefile is in place, you will be building xdb_sql
	          with PostgreSQL support.

		cd /usr/local/jabber/xdb_sql
		make

	______________________________________________________________
	11.  ADJUST JABBER.XML AS NEEDED

	If you have compiled one or more modules, you will now need to
	adjust the Jabber configuration file accordingly.  The example
	file 'jabber.xml.example' mentioned earlier should give you a 
	little insight into where changes need to be made.

	Note that often when Jabberd does not work as expected, it is
	due to some form of configuration error.

______________________________________________________________________
ADVANCED SETTINGS

Once you have the basics setup, you can refine your configuration
with one or more of the following settings.

	______________________________________________________________
	SSL SUPPORT

	In order to make use of SSL support, it is absolutely essential
	that you build a proper key file and that you adjust your jabber.xml
	configuration to point to that file.  Either following the steps in
	the Admin Guide or using the generateSSLkey script (assuming it
	is included in the distribution), build yourself an SSL key file.
	Then go through your jabber.xml file and note the <ssl port> and
	<ssl> sections especially.

	______________________________________________________________
	MINIMIZE LOG MESSAGES

	Though not necessary, to minimize error.log messages, create a
	directory for your conferences and place empty files in there as 
	follows (will use fictitious jabber-example.org to demonstrate):

		cd /usr/local/jabber/spool
		mkdir conference.jabber-example.org
		cd conference.jabber-example.org
		touch rooms.xml
		touch registration.xml

	______________________________________________________________
	RUNNING JABBERD AS AN NT SERVICE

	Using whichever method works best for you, create a _Windows_ user
	named 'jabber'.  [I tend to RIGHT-click on 'My Computer' and choose
	'Manage' from the popup menu, but there are too many ways to 
	achieve the same goal for me to list them all here.]  We will run
	the Jabber server as an NT service under this user, thereby 
	at least limiting the security implications.

	Once created, go to the 'Local Security Policy' in your
	'Administrative Tools' and add 'jabber' user to list of those who 
	can "Log on as a service".  THIS IS IMPORTANT.

	Next we need to make Cygwin aware of this new Windows user.  We do
	this by adjusting the /etc/passwd file as follows:

		mkpasswd -l -u jabber >>/etc/passwd

	At this point we need to change the permissions on all the files
	related to Jabberd under Cygwin so that user 'jabber' has ownership:

		chown -R jabber * from within /usr/local/jabber
		chown jabber jabber at /usr/local level

	And finally, we need to install jabberd as an NT service, 
	configured so that it runs under the context of Windows user
	'jabber'.  Assuming the install-as-service script is included,
	simply execute that

		./install-as-service

	and when prompted, enter the password for Windows user 'jabber'.

	If the script is not included here, you will need to use the Cygwin
	utility cygrunsrv (type 'cygrunsrv --help' for details) or something
	similar like FireDaemon to run Jabberd as a service.  For 
	example, to use cygrunsrv, the command is basically something like
	the following (\ denotes continuation on next line, as this 
	should all be typed on one line):

		cygrunsrv --install jabberd \
		--path /usr/local/jabber/jabberd/jabberd \
		--chdir /usr/local/jabber \
		--disp "JABBER Server" \
		--user jabber --shutdown

	Once installed this way, you should be able to fire up Jabberd
	using the same techniques used for other Windows services (e.g.,
	using the GUI management tools or commands like 'net start jabberd'/
	'net stop jabberd'/etc.)

______________________________________________________________________
FINAL COMMENTS

The sample scripts contained in this directory are just that:  samples.
Hopefully they will provide you with an idea of what is involved if you
wish to install Jabberd using Cygwin under Windows.

Though I have made reasonable attempts at proofreading my writing and 
making sure I do not lead you astray, any errors/typos above are mine and 
mine alone.  Apologies in advance for any grief caused.  Hopefully this 
Illiad will be of use to at least one person. :-/
