link program

First of all, Interchange requires a web server that is already installed on a system. Since Interchange is always running in the background as a daemon — parallel to your web server — there must be some means of communication established between the two.

For that reason, at startup, Interchange initializes the UNIX or INET domain socket (or both), depending on specific configuration. Few variants of a small CGI "link program" ship with Interchange and are intended to connect to one of those sockets. Then, they provide the data link to the web server (and consequently, to the users' browser).

[Note]Note

Since Apache is the most popular web server, further instructions will focus on Apache setup. If using another type of web server, some translation of terms may be necessary.

A ScriptAlias or other CGI execution capability is needed on the web server side, to allow use of the link program. The default ScriptAlias for many web servers is just /cgi-bin/. Otherwise if the ExecCGI Apache directive is set, then any program ending in a particular file suffix (usually .cgi) can be invoked as a CGI program.

By convention, Interchange names link programs after catalog IDs (catalog names as defined in interchange.cfg), though this is not required. Link program name is used to derive SCRIPT_PATH, which is then used to determine which Interchange catalog is referenced.

UNIX-Domain Sockets

UNIX domain sockets are not reachable from the Internet directly; they can only be accessed from the local host. This improves security and is the right thing to do when the web and Interchange server are running on the same host.

The link program vlink is the provided facility for such communication with Interchange. As said, this is the most secure way to run a catalog, as there is no way for systems on the Internet to interact with Interchange except through the offered link program.

The most important issue with UNIX-domain sockets and Interchange are file permissions (Unix sockets appear as files on the local disk). Interchange normally runs with the socket file having permissions 0600 (which translates to rw-------), which mandates that the CGI program and the Interchange server run as the same user ID. This means that the vlink program must be SUID to the same user ID as the Interchange server executes under. (Or that CGIWRAP is used on a single catalog system, but CGIWRAP is largely obsolete these days).

Even though this is against good security practice, let's say you can put SocketPerms 0666 in your interchange.cfg (and restart Interchange) to allow wide-open access to the socket file. In fact, you should do this when you have connection problems to quickly rule out whether it's just permissions or something else.

INET-Domain Sockets

INET sockets are reachable from the Internet directly. The link program tlink is the provided facility for such communication with Interchange. Other browsers can talk to the socket directly if mapped to a catalog with the global TcpMap directive. To improve security, Interchange usually checks that requests come from one of a limited number of "trusted" systems defined with the global TcpHost directive.

Setting up VLINK and TLINK

vlink and tlink, compiled from vlink.c and tlink.c source files, are very small, fast and low-overhead C programs that contact the running Interchange daemon. The vlink executable is normally made setuid (SUID) to the user account which runs Interchange, so that the UNIX-domain socket file can be set to secure permissions (user read-write only, as mentioned above). It is normally not necessary for the user to do anything — the link programs will be compiled by the configuration program. If the Interchange daemon is not running, either of the programs will display a message indicating that the server is not available.

Link program source files, found in dist/src/ directory with Interchange source tree, share the common C include file config.h which sets required variables:

  • LINK_FILE - name of the socket file (so, UNIX domain socket) that will be opened, usually /usr/local/lib/interchange/etc/socket (or anyhow, etc/socket under your ICROOT directory).

  • LINK_HOST - IP number of the host (so, INET domain socket) which should be contacted. The default of 127.0.0.1 (the local machine) is probably best for many installations.

  • LINK_PORT - TCP port number (so, INET domain socket) to connect to. The default is 7786 (the decimal ASCII codes for 'M' and 'V') and does not normally need to be changed.

  • LINK_TIMEOUT - number of seconds vlink or tlink should wait before announcing that the Interchange server is not running. The default of 45 is probably a reasonable value.

Compiling VLINK and TLINK

There is a compile_link program found within Interchange source tree that will assist you with link program compilation. Run perldoc PATH/TO/compile_link to read its documentation. (To find where the compile_link or compile_link.PL commands are, use locate compile_link or find / -name 'compile_link*').

Anyhow, you can also compile the link programs more "manually" if you position yourself to the Interchange source tree:

$ cd dist/src
$ ./configure
$ # (open and inspect config.h)
$ mkdir ../bin
$ perl compile.pl

After which the compiled vlink and tlink programs will be in your dist/bin/ directory.

For yet another iteration, if you want the control over the whole process, instead of perl compile.pl invoke simply:

$ gcc vlink.c -o ../bin/vlink
$ gcc tlink.c -o ../bin/tlink

The problem with the above approach, however, is that you might be missing critical compiler options, or that the compiler isn't gcc at all. To ensure that the C compiler will be invoked properly, use the following little ditty instead of the two gcc lines:

perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS vlink.c -o ../bin/vlink");'
perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS tlink.c -o ../bin/tlink");'

And finally, you can make the binaries smaller by going to ../bin/ and typing strip *, if available. (strip removes all debugging symbols from the binaries).

Have in mind that link programs are the same for all catalogs running on the same server — it's only their name that makes them refer to different catalogs. In other words, once you get one link program compiled, you can simply keep copying it to new names as you create new catalogs.

Placing VLINK and TLINK to proper system locations

First of all, if Interchange is to run under a different user account than the individual configuring the program, change vlink ownership to the Interchange user. Do not make it owned by root, because making vlink SETUID root is an huge and unnecessary security risk. It should also not normally run as the default Web user (often nobody or http>).

Here's a prospective session transcript (starting in dist/bin/):

# Set up ownership and suid bit
chown INTERCHANGE_USER vlink

# Move the vlink executable to the cgi-bin directory:
mv vlink /usr/lib/cgi-bin/CATALOG_NAME

# Most systems unset the SUID bit when moving the file,
# that's why we add suid here and not above:
chmod u+s /usr/lib/cg-bin/CATALOG_NAME

VLINK or TLINK compile problems

The latest versions of the link programs have been compiled on the following systems:

  • AIX 4.1

  • BSD2.0 (Pentium/x86)

  • Debian GNU/Linux

  • Digital Unix (OSF/Alpha)

  • FreeBSD 2.x, 3.x, 4.x

  • IRIX 5.3, IRIX 6.1, IRIX 6.5 (both SGI MIPSPro and GCC; remove -lnsl -lsocket from syscfg file on IRIX 6.x)

  • OpenBSD 2.7

  • Red Hat Linux 6.2, 7.0, 7.1, 7.2, 7.3, 8.0

  • SCO OpenServer 5.x

  • Solaris 2.x (both Sun compiler and GCC)

  • Solaris 7 (both Sun compiler and GCC)

  • SunOS 4.1.4

If nothing works and you have a problem, you can try using the tlink.pl program found in the same location as link and tlink. tlink.pl is a tlink implementation written in Perl and should work on a really broad range of systems. In any case, unless you are using tlink.pl for a specific reason, and you do have a working compiler, tuning the C source files to overcome compilation problems is preferred over using Perl implementation of the link program.

DocBook! Interchange!