Installation, and requirements

LibCXX uses Linux-specific APIs. An earlier version of LibCXX could also be be built on FreeBSD 10, but the port is not maintained at present, see Appendix A, Porting and compatibility notes for more information.

LibCXX targets the current generally-available version of gcc, and code that uses LibCXX should use -std=c++17 -fno-omit-frame-pointer options to compile. 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.

  • The current generally-available version of GCC. As new GCC releases include support for new C++ standards, this library gets accordingly.

  • The CUPS libraries.

  • The Courier Unicode Library.

  • gnutls, libgcrypt (at least 1.6), libidn, libxml2, libxslt, libyaml and pcre.

  • libtool, autoconf, automake, and gettext.

  • pkg-config.

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

Configuring and building

As mentioned above, LibCXX should be built into a standalone, installable package. Use the following documentation as a guide to create an installation script or a package.

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 ephemeral 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 ephemeral 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, making LibCXX immediately usable after installation. Include the pregenerated 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 stock ephemeral parameters with randomly-generate ones.

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 stock 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. Any existing ephemeral parameter files, from a previously-installed version of LibCXX, get preserved.

    Therefore, LibCXX is usable immediately after installation, and only a new install has the 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 stock files, and runs tlsparamsgen in the background, immediately. The RPMs also install a monthly cron job to generate new parameter files.

The final result is that LibCXX package gets installed without lengthy delays for generating ephemeral parameter files, at installation time. This happens in the background 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.