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 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.

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:

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.

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

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

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.