============================= Swamp 1.1.0, INSTALL document ============================= Swamp, as of this version, is now autoconf-controlled. This should make it easier to get it building and running on platforms other than ... well, other than my desktop I suppose. :-) However, that's not to say that; (a) the autoconf support is all that good (yet), or (b) that all portability issues are currently tested and handled Feedback on either point is extremely welcome, and is especially glorious when described in text *and* accompanying patch file ("diff -urN" preferred). At the very least, please send details of your compiler, operating system, the nature of the problem, and *NO* large binaries or core-dumps. This document contains a few slim points that should get you started - this is an improvement (I hope you'll agree) over the previous version, but the documentation is still a little on the "lite" side. For other types of information see; README: General discussion of what swamp is, how to use it, and why it exists. LICENSE: Rule and regs about redistribution of swamp, or incorporation into other projects or commercial products/distributions. CHANGES: A list summarising changes in swamp over time/versions, and the names of (and thanks to) those who made them happen. FAQ: A list of "Frequently Asked Questions" about swamp. FYI: Swamp is written by Geoff Thorpe (swamp@geoffthorpe.net), as is this dinky little document. The major contributors to swamp thus far are; Steve Robb Please see CHANGES for more info on "who?", "when?", and "what exactly?". ======== Sections ======== Section I: Pre-requisites to building swamp Section II: Building swamp Section III: Bugs, problems, etc. =========================================== Section I: Pre-requisites to building swamp =========================================== To build swamp you will need to have; (i) The swamp source code, which you should probably already have if you're reading swamp's "INSTALL" document. :-) (ii) An adequate version of OpenSSL on your system, and not just binaries but the OpenSSL headers and libraries too. (iii) An adequate compiler installed (gcc, commercial "cc"s are usually OK, see section III for warnings though). (iv) An adequate "make" that can handle automake's output. If you're not using GNU make, See section III. (i), if it is not already satisfied, can be obtained by surfing to; http://www.geoffthorpe.net/crypto/ and looking for info on where "swamp" can be downloaded from. For (ii), it will depend on whether or not you are dealing a version of OpenSSL that is already installed or is available in the media of some pre-packaged system. If you do not have "direct" access to OpenSSL (it's installed or you have packages available already), you can find source code from the OpenSSL website; http://www.openssl.org/ (and take the link to "source"). The rest of this section assumes you have already found OpenSSL if you didn't already have it. RPM-based OpenSSL installations (or via similar packaging systems): ------------------------------------------------------------------- The OpenSSL source itself is not required, but the development headers and libraries are. So for RPM-based systems, this usually means that you need to have the RPM with the "openssl***-dev***.rpm" name installed in addition to the base "openssl***.rpm" package. You should not however need any "openssl***-src***.rpm" package (though having it probably won't hurt anything). Manual (or custom) OpenSSL installations: ----------------------------------------- You can build swamp using your own installation of OpenSSL, even if another version of OpenSSL headers and libraries is already installed in system-wide locations (eg. perhaps you don't have root-access and choose to run your own local installation of OpenSSL customised for your purposes). This works exactly the same as the "OpenSSL source tree" case below (ie. you will use the "--with-ssl" option to the "./configure" script), and the only systematic difference is that the autoconf-generated "configure" script will notice that the libraries exist in a "libs/" sub-directory of your OpenSSL installation whereas the "source tree" version have the libs in its top-level directory. Using a compiled OpenSSL source tree: ------------------------------------- If you have a version of OpenSSL you wish to use and have extracted the source code and compiled it there (without installing via "make install") you can instruct swamp to build using this version/compilation rather than looking for (and automatically using) any system-wide OpenSSL installation. You need to ensure that your OpenSSL source tree has been configured and built correctly, a la; [bob@wherever ~/dev/openssl] ./config [bob@wherever ~/dev/openssl] make [bob@wherever ~/dev/openssl] make test Then when building swamp (see below), use the "--with-ssl=" option to swamp's "configure" script. NB: Swamp will *not* configure and build if you leave the OpenSSL source tree uncompiled, you must build OpenSSL properly before configuring/building swamp. ========================== Section II: Building swamp ========================== Building swamp will be fairly straightforward to anyone familiar with building autoconf-style applications. The only possible problems could be per-platform oddities (see Section III). These would, in part, be caused by the author's lack of familiarity with all the sick weirdness that goes on behind the scenes of the GNU autotools (at this point in time, the author is not sure whether that lack of familiarity is a good thing or not). Configuration ------------- Swamp is configured for building by using the "configure" script. This script will check for a working compiler, whether certain standard (though sometimes missing because they're arranged differently) headers exist, and probe other per-system settings. Most of this "just works" to come up with the right settings for your needs. If you are trying to build swamp as part of a binary toolkit that you would like to work on a wider array of systems than the one you're building on, (in which case you'll also find time to read the "LICENSE" file), you may have to give some thought to using various "configure" settings ("--prefix", "--target", etc) to ensure the build you get is vanilla enough to run across the hosts you need. Cross-compilation is left as an exercise for the reader, for example. :-) There are two options provided to swamp's "configure" script in addition to the standard autoconf options, and you can view all these available options by running; [bob@wherever ~/dev/swamp] ./configure --help The two options that are of particular interest are; (i) "--enable-custom-cflags=[args] add extra flags to the compilation" (ii) "--with-ssl=/path/to/openssl use the provided OpenSSL installation" Eg. to configure swamp, located in ~/dev/swamp, to build using an OpenSSL source tree (or installation - the distinction is autodetected) at ~/dev/openssl, and to add extra debugging (gcc-only) flags to the build, you might use; [bob@wherever ~/dev/swamp] ./configure \ --with-ssl=../openssl \ --enable-custom-cflags="-Wall -ggdb3" The path provided to the "--with-ssl" option can be relative or absolute to the swamp build directory - the "configure" script will convert any relative path to an equivalent absolute path during processing anyway. Note also that the output from "configure" will indicate whether or not it found "ENGINE" support in the OpenSSL headers/libraries. This will affect whether or not the compiled "swamp" will support the "-engine " command-line switch, and thus whether it is able to use alternative crypto implementations and/or hardware acceleration. Compiling --------- After configuration, all that is normally required to have "swamp" build to completion is to simply issue the command; [bob@wherever ~/dev/swamp] make The result should build an executable "swamp" in the directory. You can quickly test that by asking the swamp executable to display its command-line options by; [bob@wherever ~/dev/swamp] ./swamp --help Also, if you wish to install swamp, you can do so by running; [bob@wherever ~/dev/swamp] make install However, unless you used the "--prefix=/install/path" option to the "configure" script, this will try to install swamp in some canonical system location that probably requires you to be runnning "make install" as the 'root' user. Also, there are currently no "man" pages, libraries, headers, or config files associated with swamp so this "installation" will consist of nothing more than copying the "swamp" executable to some system location where all users can run it. There are issues associated with compiling swamp on some systems however, and moreover the installation (or binary distribution) of a compiled version of swamp has other issues that depend on the configuration. These are covered in Section III. If you discover "new" problems that aren't mentioned - it's probably because I haven't tried your system or your idea yet so don't know about the consequences. Please let me know if you stumble into something like this. ================================= Section III: Bugs, problems, etc. ================================= Makefiles --------- The "Makefile" used to build "swamp" is generated from the "Makefile.in" file by the "configure" script after it has finished probing system settings and processing any parameters passed to it. "Makefile.in" itself is/was generated from a far simpler-looking file called "Makefile.am" using "automake". "Makefile.am" may not be present in the distributed source, and it's not really that relevant anyway. What *is* relevant is that because automake generates the (complicated) input file "Makefile.in" that gets converted to "Makefile", any platform-hassles created by "automake" are hard to work around. Eg. On OpenBSD and Solaris-7 (aka SunOS 5.7) at least (and quite possibly others), the generated Makefile *does not work* with the system-native "make" command. Ie. does not work *at all*. --- OpenBSD --- On OpenBSD, this can be *partially* worked around by identifying the syntax that "make" doesn't like and getting rid of the corresponding line in "Makefile.in" before running (or rerunning) "configure". At the time of writing, the one case I noticed on OpenBSD was a complete line, with a blank line before and after it, that had the following form; -include $(DEP_FILES) That was around line 284 of Makefile.in, at the time of writing. Removing that line allowed OpenBSD's "make" to process the generated Makefile without error in my own test. However, problems remain - OpenBSD's "make" does not pass environment from one invocation to the next the way GNU "make" (aka "gmake") does. Depending on how swamp was configured to use OpenSSL, this can result in the build failing to find OpenSSL headers, ignoring addition flags provided by "--enable-custom-cflags", and possibly other things. I would love to work around this, but it would require someone with a better understanding of "automake" to do so. In the mean time, the easiest (though least acceptable) solution is to use GNU make. On OpenBSD at least (again, this probably applies to other BSD systems as well), "gmake" is available in the "ports" system in the ./devel/gmake/ subdirectory. Once "gmake" is built and installed, you should simply be able to type "gmake" rather than "make" to build swamp and all should be well in the universe again. --- Solaris --- Solaris's "make" has other difficulties with the generated Makefile that were less obviously fixable. I had to use "gmake" to have the Makefile parse successfully at all. However, when building with "cc" rather than "gcc", the automake-generated Makefile calls "cc" using flags that don't seem to be supported, in the name of dependency generation. I had to hand-edit the Makefile where the "%.o:" target is defined (around line 295 at the time of writing). Here is the exact change, although the second part ("%.lo", libtool support) isn't used and so could be ignored. -------------begin "diff -u" output------------------- --- Makefile.orig Tue Aug 28 14:09:50 2001 +++ Makefile Tue Aug 28 14:09:56 2001 @@ -294,22 +294,11 @@ %.o: %.c @echo '$(COMPILE) -c $<'; \ - $(COMPILE) -Wp,-MD,.deps/$(*F).pp -c $< - @-cp .deps/$(*F).pp .deps/$(*F).P; \ - tr ' ' '\012' < .deps/$(*F).pp \ - | sed -e 's/^\\$$//' -e '/^$$/ d' -e '/:$$/ d' -e 's/$$/ :/' \ - >> .deps/$(*F).P; \ - rm .deps/$(*F).pp + $(COMPILE) -c $< %.lo: %.c @echo '$(LTCOMPILE) -c $<'; \ - $(LTCOMPILE) -Wp,-MD,.deps/$(*F).pp -c $< - @-sed -e 's/^\([^:]*\)\.o[ ]*:/\1.lo \1.o :/' \ - < .deps/$(*F).pp > .deps/$(*F).P; \ - tr ' ' '\012' < .deps/$(*F).pp \ - | sed -e 's/^\\$$//' -e '/^$$/ d' -e '/:$$/ d' -e 's/$$/ :/' \ - >> .deps/$(*F).P; \ - rm -f .deps/$(*F).pp + $(LTCOMPILE) -c $< info-am: info: info-am dvi-am: -------------end "diff -u" output------------------- OpenSSL libraries ----------------- If you built swamp on a system using a pre-installed version of OpenSSL (ie. you didn't need the "--with-ssl" parameter), there's a good chance, sadly, that you have built swamp to use a shared-library version of OpenSSL. This means that swamp does not contain a copy of the crypto/SSL/TLS code that it needs from OpenSSL, it will dynamically load the "libssl.so" and "libcrypto.so" shared libraries at run-time. This is a problem for two reasons, one tolerable and other less so. (tolerable) encapsulation: because the swamp executable doesn't contain it's own copy of the parts of OpenSSL it needs, it can't simply be placed on a system and expected to work. It will fail to start at all unless the system-loader can resolve it's dependency(ies) on the shared-library(ies). Ie. if the target system doesn't already have the OpenSSL shared libraries installed as well, the swamp executable will not run. Moreover, some platforms have wildly different binding rules for executables and shared libraries, so the compiled "swamp" may even require the OpenSSL shared libraries to live in exactly the same path as it originally found them on the system swamp was built on. This is also affected by the "intolerable" reason; (intolerable) versioning: despite repeated warnings, statements, and confirmations by the OpenSSL authors, many UNIX-like distributions build and bundle OpenSSL in shared-library form. OpenSSL is in a state where most of the development tasks in-progress and on the TODO list will involve changes that affect binary compatibility and *behavioural* compatibility from one version to the next. The authors have stated on more than one occasion that no binary compatibility can be expected or should be assumed between one version and the next. Thus if your system has 10 applications depending on a particular version of OpenSSL and a new application depending on a different version, you will be in a great deal of trouble if you try to have them all using shared-library forms of OpenSSL installed in the system itself. Shared-library support itself inside OpenSSL is marked "experimental" and should probably only be used for local installation by packages that wish to reduce their installation size by having a number of applications in the same "bundle" use a single copy of OpenSSL functionality. This is OK because that package can be upgraded and, if required, a newer version of its own local OpenSSL shared library can be installed at the same time. Ie. they can be managed to be consistent amongst themselves. However, vendors installing OpenSSL as *system-wide* shared-libraries, to be used by arbitrary applications that have no relationship or version-control between them, is ... *stupidity*. And you can tell your distribution vendor I said so if you like. (And give them my OpenSSL mailing address if you do so: geoff@openssl.org).