Installation, and requirements

LIBCXX uses Linux-specific APIs; and with one exception LIBCXX compiles only on Linux, The exception is that currently it builds on FreeBSD 9.1 with an alternative implementation of Linux-specific APIs, see Appendix A, Porting and compatibility notes for more information.

gcc 4.7 is required. Since this library uses C++11 classes, applications must be compiled with the -std=c++0x option, as well as -fno-omit-frame-pointer. This is done automatically when using autotools.

LIBCXX should be converted into an installable package, instead of building and installing LIBCXX directly. The source tarball includes a canned build script for Fedora. Running rpm -ta libcxx-version.tar.bz2 creates the following packages:

Use the following documentation to build LIBCXX without the bundled RPM script.

Requirements and prerequisites

  • A filesystem that implements extended file attributes. This is usually the case these days. Some older Linux systems, that have been upgraded for a long period of time, might be still on a filesystem without extended attribute support; but it's usually a simple command or two to enable this.

  • GNU make; if it's installed as gmake, use that in place of the make command.

  • GCC version 4.7, or a higher version if it's the current current version of GCC. As new GCC releases improve support for C++11, this library will probably be updated to take advantage of them.

  • gnutls, libgcrypt, libidn, libxml2, libxslt, libyaml and pcre.

  • pkg-config.

  • An installed list of default certificate authorities, in /etc/pki/tls/cert.pem by default.

  • Other non-Linux platforms (currently consists of one specific version of FreeBSD) might have additional requirements for Linux compatibility.

Configuring and building

Run the configure script, followed by make (or gmake). configure takes the usual options that specify non-default installation directories, for various files. Additional options are:

--with-pkgconfigdir=dir

Specifies where pkgconfig configuration file gets installed. The configure script goes through the list of some common directories, and checks if they exist.

This option may be needed to override the default even if configure finds it, and does not complain, if it ends up finding and installs its pkgconfig file into the wrong directory.

--with-cacerts=file

Specifies the file with a list of trusted certificate authorities. The configure script knows about some common locations, and will check them. If it can't find it, and complains, use this option to tell it where it is.

When building LIBCXX, for the first time, it's also a good idea to run (g)make check, but that shouldn't be a part of an automated build script, since it may fail on a heavily loaded build server, due to some test scripts' timing.

Run (g)make install DESTDIR=/tmp/libcxx-install. This creates an installation image in the /tmp/libcxx-install directory, to use as a basis for creating an installable package. A plain (g)make install will do it for real, of course. However, using an installable package is strongly recommended.

Regenerating emphemeral DSA and RSA parameters

This is required by LIBCXX's API for the GnuTLS library. Generating these parameters is often a time-consuming task, depending on the hardware, so LIBCXX loads pregenerated parameters from a file. The files are located in localstatedir/tlsparams, which is usually /usr/local/var/tlsparams or /var/tlsparams. These parameter files should be periodically regenerated. The process for doing so is as follows:

The tlsparamsgen regenerates the parameter files in localstatedir/tlsparams. make install creates a tlsparams subdirectory in sysconfdir (usually /usr/local/etc or /etc). This directory contains files with options for the tlsparamsgen script. Then, the tlsparamsgen.sh wrapper script (installed in sbindir, which is /usr/sbin or /usr/local/sbin) reads these options, and runs tlsparamsgen to regenerate the emphemeral files. A regularly-scheduled job should be scheduled to run this script (a monthly frequency is fine).

make install runs a script that generates an initial set of ephemeral parameter files, so that LIBCXX is immediately usable after installation. However, the initial emphemeral parameters are low security, generated with a minimum number of bits. This is because full, high security parameter files may take hours to be generated, depending on the hardware (and even the low security ones can take several minutes). This is fine for some job that runs monthly at off-peak times. but this does not work very well for a canned build script. The recommended approach is the following compromise:

Include the pregenerated low security ephemeral parameter files in the installable package. Then, as part of the package installation, the package should make arrangements to execute tlsparamsgen.sh soon after installation, to replace the low-security ephemeral parameters.

This is taken care of by the Fedora package. No manual action is required with the Fedora packages. All of this is described for documentation purposes only.

Furthermore, the Fedora package uses a slightly more robust approach, as follows:

  • The INSTALL_TLSPARAM_SUFFIX=.dist parameter to make install installs the low-security ephemeral parameter files with a .dist suffix. This is what goes into the RPM package.

  • A post-install script checks if each ephemeral parameter file already exists, or not, and only links the installed .dist file to the real one if it does not exist. So, if there are already high security ephemeral parameter files from a previously-installed version of LIBCXX, they get preserved.

    Therefore, LIBCXX is usable immediately after installation, and only a new install has the low security stock ephemeral parameters until the first reboot, because:

  • The startup script that runs at boot time, to start httportmap, checks if parameter files are the initial low security ones, and runs tlsparamsgen in the background, immediately. The RPMs also install a monthly cron job to generate new parameter files.

The end result is that LIBCXX package gets installed without lengthy delays for generating ephemeral parameter files. This occurs during the first reboot after installation. And going forward, the cron job in the package regenerates them monthly.

Installing and starting httportmapd

The httportmapd daemon is a part of LIBCXX. A package that installs LIBCXX needs to execute the properties command to configure httportmapd's property file. This is done by make install, however property files are stored in extended attributes, which are typically not preserved by binary package file formats. This usually needs to be done after LIBCXX package's installation.

The property file is httportmapd.properties, and it gets installed in sysconfdir, which is usually /usr/local/etc, or /etc. httportmapd gets installed in sbindir, which is usually /usr/local/sbin, or /usr/sbin; and the properties command gets installed into bindir, which is usually /usr/local/bin, or /usr/bin:

/usr/bin/properties --set /usr/local/etc/httportmapd.properties /usr/local/sbin/httportmapd

Afterwards, arrangements must be made to have httportmapd started during system boot:

/usr/local/sbin/httportmapd --http --daemon start

This forks and runs the portmapper as a child process. The portmapper process opens and binds the HTTP port 80, to handle portmapper service requests. httportmapd stop may be added to the system shutdown script, to stop the daemon process.

Leave out the --http if there's already an HTTP server, such as Apache on port 80. In that case, the portmapper expects to be invoked as a CGI application for all http://hostname/portmap URLs (that is, in addition to the daemon instance which still needs to get started). In the source tarball, httportmap/apache.conf.in is a sample Apache configuration, with a placeholder for httportmapd's installation location.