To understand this document

This document describes a very simple network service. If you have ever used interactive FTP or telnet you should be fine. If you want to do the examples you will need to be able to run commands as the superuser to exit file under /etc.

What is `tcpmux`?

The manual page describes tcpmux as an implementation of RFC 1078. That (genius) document describes the simplest service oriented architecture ("SOA") application protocol ever implemented. Clients connect on port 1, they immediately ask for a service by name, they get either a line that starts with a plus (+) for a successful connection, or they get an error message.

This simple remote procedure call lacks any document encoding, or hypertext transport headers, or markup. So it is very easy for system admins to use. Since you can do it all with shell scripts and perl programs.

Most implementations of inetd had an implementation of tcmpux included, until recently. Since xinted doesn't include one I coded a stand-alone version that you can configure to support local services.

This allows an administrator to put an anonymous data service up on any given host. Such a service might map a uid to a login name, or map a hostname to an on-call support group. It could display diagnostic information for triage or disk error reporting. It should never assume that the client is secure, or that the channel is secure. That means you don't put anything on the wire that you wouldn't post to Facebook™.

When would you use a mux service?

I have a bunch of them.

dumpmux: Runs backups for all my hosts. This service checks the incoming IP address to see if it is in a DNS record that lists the current backup servers. Which is secure enough for a private local (RFC 1918) backup network.
fetchdump: The client-side of dumpmux.
recvmux: Stashes away status from a client host into a spool directory for weekly or monthly reporting.
imux: Reports on the patch/version information about a host. This can confirm that a group patch-set succeeded on every host, or that new hosts were build with the correct patches.
msrcmux: Streams a customized tar archive of a configured master source layer2 directory to the client. This shadow copy is usually unpacked, installed, and deleted by the client.
nodelist: Lists all the hosts that are under the control of a given policy domain.
probemux: Allows a load balancer to interact with the applications on a host.
vcsmux: Reports on the current VCS status. Helps operators get fast status from lots of machines with a multi-threaded status tool.
uid, gid: Accounting requests to map a login-name to/from a uid, or map a group name to/from a gid. This is used to report a missing account on a host (since you always know either the name or the uid but maybe not the other).
... and to many more ...: The limit on these services is privacy and security: in most of the cases above anyone with a shell on the host serving the request could have found the information without any special access. For example mapping a uid to a login only requires access to /etc/passwd, which all logins have.

Try it

If you have superuser access on a host you can install tcmpux with your local msrc policy, or from a local RPM repository.

Run the mux from the command-line to see where the configuration file should be located:

/usr/local/libexec/tcpmux -V
tcpmux: $Id: tcpmux.html,v 1.6 2012/03/21 16:15:05 ksb Exp $
tcpmux: configfile: `/etc/tcpmux.conf' [No such file or directory]
tcpmux: compile options: redirection, recursive calls

Then put a line in tcpmux.conf to test the service:

motd stream tcp nowait man /bin/cat cat /etc/motd

Try it with a raw telent. Connect to localhost on port 1, ask for "motd" (which is the name of the module in column 1):

telnet localhost 1
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
motd
FreeBSD 9.1-STABLE (KSB) #2: Wed Jun 30 15:00:00 CDT 20l2

Connection closed by foreign host.

There are two programs in /usr/msrc/local/bin/ that make it easier to drive tcpmux services from the shell:

muxcat: Connect to a tcpmux service and expect a stream of data.
muxsend: Connect to a tcpmux service and send a stream of data to that service.

Both of these have a limited ability to dig through layers of mux encapsulation. That is to say that they will present each command-line parameter to the service they connect to in turn, until the last one is sent. If each layer returns a positive acknowledgment (a line that starts with a plus-sign (+) then the process continues until all the command-line parameters have been sent and acknowledged.

This allows services to refine the request for data before the send (or receive) the "payload". See the muxcat and and muxsend manual pages for details. Also see the msrc directory for muxcat and muxsend, which contain the perl source files.

Example services

In this directory the file publish.pl is an example script that just sends a fixed file back to the client. It is the example that muxcat and muxsend were built from. It is less configurable, so is a little more secure as a service.

In the master source for dumpmux there is a C program (with a mkcmd wrapping) that dumps a filesystem by a short name. There is also an older perl prototype of the same dumpmux program. The client for the dumper program is called fetchdump, see the source for it.

Why do I claim the mux is the basis of the SOA stack?

You have to walk before you can run. If you are building a complete SOA stack for you applications, then you might to build the supporting structure along a similar path. If operations and applications take vastly different structural paths to create the service clouds you might find that the needs of one dominate the reliability and quality of the other.

At least I've found that to be true.

When both layers follow the same rules for deployment of services, failover, and scaling models you'll have more agreement on how to solve common issues. Lack of agreement on design always makes little issues into big issues.