.\" $Id: msrcmux.man,v 1.12 2012/07/09 21:12:13 ksb Exp $ .\" by KS Braunsdorf .\" $Compile: Display%h .\" $Display: ${groff-groff} -Tascii -man -tbl %f | ${PAGER-less} .\" $Display(*): ${groff-groff} -T%s -man -tbl % f .\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man7/msrcmux.7 .\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/msrcmux.7* .TH MSRCMUX 7 LOCAL .SH NAME msrcmux - offer platform archives of any level2 master source directory .SH SYNOPSIS .ds PN "msrcmux \fI\*(PN\fP [\fB\-Mx\fP] [\fB\-C\fP\~\fIconfigs\fP] [\fB\-E\fP\~\fImmsrc\fP] [\fB\-L\fP\~\fIhxmd-libs\fP] [\fB\-R\fP\~\fIreverse\fP] [\fB\-X\fP\~\fIex-config\fP] [\fB\-Z\fP\~\fIzero-config\fP] [\fImsrc-root\fP] [\fIenv\fP=\fIvalue\fP] .br \fI\*(PN\fP \fB\-h\fP .br \fI\*(PN\fP \fB\-V\fP .SH DESCRIPTION This program runs as a \fBtcpmux\fP service (usually under \fBinetd\fP) on the master source server to build shadow copies of master source directories customized for each client. The resulting directory is sent as a \fBtar\fP(1) archive over the network. By unpacking that content into a local shadow hierarchy the client host may maintain an autonomous \*(lqpull version\*(rq of the master source. .P The \fBmpull\fP(8) application copies a master source directory to the localhost, then builds the shadow copy. The difference is the meta-data used to configure the shadow copy: in the \fBmpull\fP case the meta data is from the client, with \fI\*(PN\fP the meta-data is taken from the central server. Either tool may be required depending on the meta-data context, and local site policy. .PP The \fI\*(PN\fP service recognizes each client via \fBgetpeername\fP(2) and a reverse DNS lookup on the resulting IP address. If the reverse lookup fails the proposed name of the host is \fB@\fP (commercial at), which cannot be part of a real hostname. .PP The \fBtcpmux\fP configuration for this service looks like: .nf \fImsrcmux\fP stream tcp nowait \fIsource\fP /usr/local/libexec/msrcmux msrcmux \fImsrc-root\fP .fi Where \fIsource\fP is the name of a safe login to run the service, and \fImsrc-root\fP is the path to the master source top-level directory. Other options may be inserted before the \fImsrc-root\fP parameter. .PP Most clients connect with \fBmuxcat\fP to access the service. The standard usage via that interface is: .nf \fBmuxcat\fP \fImsrcmux\fP \fImaster\fP \fIconfig\fP [>\fItarfile\fP] .fi Where \fImsrcmux\fP is the exposed service name, \fImaster\fP is the path from the \fImsrc-root\fP to the requested product (level2) directory, and \fIconfig\fP is either a literal dot (\fB.\fP) or a colon separated list specific meta-data configuration files which are even to \fBmmsrc\fP under \fB\-C\fP, see \fBmmsrc\fP(8). .P Usually the output is redirected to a file, or unpacked directly with \*(lq|tar xf \-\*(rq. Note that every \fBtar\fP archive is rooted at \fB.\fP, therefore it is best to unpack each archive in a new directory. The resulting directory has conservative permissions: only owner access is granted by default. Override this with a \fBchmod\fP after unpacking the archive. .SH OPTIONS No options are forced based on the name of the program. Assignments after the options are copied to the process environment. .TP .nf \fB\-C\fP \fIconfigs\fP .fi A colon separated list of the default client \fIconfigs\fP. The assumed value of \*(lqauto.cf\*(rq presumes that all your hosts look just like the server. Local site policy should pick a better value. .TP .nf \fB\-E\fP \fImmsrc\fP .fi The name of the program to run which generates the \fBtar\fP output, if not \*(lq/usr/local/sbin/mmsrc\*(rq. The option specification to this program is explained in BUILDING, below. .TP .nf \fB\-L\fP \fIhxmd-libs\fP .fi A colon separated list of directories to search for configuration files and \fBMAP\fP'ed files. This \fBmust\fP contain the current directory for any local \fBMAP\fP macros to work. The error below indicates that the value specified did not contain \fB.\fP (the current directory): .nf mmsrc: Makefile.host cannot find file .fi .TP .nf \fB\-h\fP .fi Print a brief help message. .TP .nf \fB\-M\fP .fi This implements a site policy requiring minimal information over the wire protocol. The intermediate protocol replies are stripped of meaning. .TP .nf \fB\-R\fP \fIreverse\fP .fi Consult the \fIreverse\fP file via \fBmk\fP(1l) to search for the correct host based on the \fImarker\fP returned by \fBgethostbyaddr\fP(3) and the IP \fIsubmarker\fP returned by \fBgetpeername\fP(2). When no name was found the marker will be commercial at (\fB@\fP). The \fB\-s\fP and \fB\-l0\fP options are also so, as well as the name of the configuration file(s) specified under \fB\-DCONFIG=\fP\fIconfig\fP. When the \fIreverse\fP filename is dot (\fB.\fP) then the specified configuration file is searched. .sp When the command \fBexit\fP's non-zero, or the resulting output contains white-space, or is zero length the client is notified that no such host exists. .TP .nf \fB\-V\fP .fi Show only the programs version information and exit. .TP .nf \fB\-x\fP .fi Trace replies from the remote service on \fIstderr\fP. .TP .nf \fB\-X\fP \fIex-config\fP .fi Passed on to \fBmsrc\fP, only 1 instance of this option is allowed. .TP .nf \fB\-Z\fP \fIzero-config\fP .fi Similarly to \fB\-X\fP, this option is passed on to \fBmmsrc\fP. These options are often used to set the attribute macro \fBMSRCMUX\fP to the name of the RFC1078 service. This allows \fBmsrc\fP-driven \fIMAP\fP files to added extra features to generated files. For example \fUlocal/lib/hxmd\fP's added more information to \fUauto.cf\fP when driven from the mux. .SH BUILDING \fBMsrcmux\fP builds an empty temporary directory (\fIstage\fP), then calls \fImmsrc\fP to produce the tar output as: .nf \fImmsrc\fP \-yINTO=\fIstage\fP \-lDHOST=\fIclient\fP \-C\fIconfig\fP \-\- tar cf \- . .fi That command is run from \fImsrc-root\fP/\fImsrc-dir\fP, which should have the required recipe file and master copies of the source required. .PP It is possible to hook into the process with \fB\-E\fP's \fImmsrc\fP specification to replace the default action with another. For example the script below runs \fBgzip\fP to compress the stream for the client: .nf #!/bin/sh exec 0/tmp/oue.tar .fi Ask the server \*(lqsulaco\*(rq for a platform copy of \fBoue\fP's source, produced with meta-information from \fIsite.cf\fP with respect to our host. Unpack that archive to build the product. .TP .nf muxcat \-x sulaco msrcmux Pkgs/msrc_base \fIsite.cf\fP .fi Request the source to a package, which fails because package directories have an injunction against pushing to any host (they only build archives). Trace the replies to see this is not a protocol issue. .TP .nf muxcat sulaco zmmux local/bin/oue . |gzip \-dc |tar xf \- .fi Pull a compressed platform copy of \fBoue\fP from the server's default meta-configuration file, uncompress it, and unpack it in this directory. .TP .nf muxcat \-h .fi Output the standard help information, which includes the default values for the options with specifications. .TP .nf # $*(127.0.0.1): hostname .fi An example configuration file comment which allows the localhost to service itself. This assumes that the name of the host in the configuration file is the same as that returned by \fBhostname\fP(1). .TP .nf # $@(10.8.13.55): echo sulaco.npcguild.org .fi The local domain's reverse for the \fIsulaco\fP reverses to a CNAME, patch it here to allow client updates by the FQDN. .TP .nf # $*(*): ${echo:-echo} %M .fi Allow any machine we do not have a rule for to try the name \fI\*(PN\fP found in the specified (or default) configuration file. .TP .nf # $*(*): exec %b %ol0 \-m'%m' \-d'%s' $CONFIG_FILE .fi Try to chain to the configuration file at the end of the \fIreverse\fP map. This excludes the use of the previous example. .SH BUGS None known. .SH AUTHORS Kevin S Braunsdorf, Npcguild.org .br msrc at ksb.npcguild.org.no-spam .SH "SEE ALSO" .hlm 0 muxcat(1l), mmsrc(8l), tcpmux(8l), mk(1l), tar(1), gzip(1), getpeername(2), dumpmux(1l), muxcat(1l), muxsend(1l), recvmux(1l), tcpmux(8) or tcpmux(8l), inetd(8), xinetd(8),