MSRCMUX(7)                                                          MSRCMUX(7)



NAME
       msrcmux - offer platform archives of any level2 master source directory

SYNOPSIS
       msrcmux [-Mx] [-C configs]  [-E  mmsrc]  [-L  hxmd-libs]  [-R  reverse]
       [-X ex-config] [-Z zero-config] [msrc-root] [env=value]
       msrcmux -h
       msrcmux -V

DESCRIPTION
       This program runs as a tcpmux service (usually under inetd) on the mas-
       ter source server to build shadow copies of master  source  directories
       customized  for  each  client via msrc(8l).  The resulting directory is
       sent as a tar(1) archive over the network.  By unpacking  that  content
       into  a  local  shadow  hierarchy  the  client  host  may  maintain  an
       autonomous "pull version" of the master source.

       The mpull(8) application copies a master source directory to the local-
       host,  then  builds  the  shadow copy.  The difference is the meta-data
       used to configure the shadow copy: in the mpull case the meta  data  is
       from  the  client, with msrcmux the meta-data is taken from the central
       server.  Either tool may be required depending on  the  meta-data  con-
       text, and local site policy.

       The  msrcmux  service  recognizes  each client via getpeername(2) and a
       reverse DNS lookup on the resulting IP address.  If the reverse  lookup
       fails  the proposed name of the host is @ (commercial at), which cannot
       be part of a real hostname.

       The tcpmux configuration for this service looks like:
            msrcmux stream tcp nowait source /usr/local/libexec/msrcmux msrcmux msrc-root
       Where source is the name of a safe login to run the service, and  msrc-
       root  is  the  path  to  the  master source top-level directory.  Other
       options may be inserted before the msrc-root parameter.

       Most clients connect with muxcat to access the service.   The  standard
       usage via that interface is:
            muxcat msrcmux product config [>tarfile]
       Where msrcmux is the exposed service name, product is the path from the
       msrc-root to the requested level 2 product  directory,  and  config  is
       either  a  literal  dot (.) or a colon separated list of specific meta-
       data configuration files  which  are  given  to  mmsrc  under  -C,  see
       mmsrc(8).

       Usually  the  output is redirected to a file, or unpacked directly with
       "|tar xf -".  Note that every tar archive is rooted at ., 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 chmod(1) after unpacking the archive.

OPTIONS
       No  options  are forced based on the name of the program.   Assignments
       after the options are copied to the process environment.

       -C configs
              A colon separated list  of  the  default  client  configs.   The
              assumed  value  of  "auto.cf"  presumes that all your hosts look
              just like the server.  Local site policy should  pick  a  better
              value.

       -E mmsrc
              The  name  of the program to run which generates the tar output,
              if not "/usr/local/sbin/mmsrc".   The  option  specification  to
              this program is explained in BUILDING, below.

       -L hxmd-libs
              A  colon  separated list of directories to search for configura-
              tion files and MAP'ed files.   This  must  contain  the  current
              directory  for  any  local  MAP macros to work.  The error below
              indicates that the value specified did not contain .  (the  cur-
              rent directory):
                   mmsrc: Makefile.host cannot find file

       -h
              Print only a brief help message.

       -M
              This implements a site policy requiring minimal information over
              the  wire  protocol.   All  intermediate  protocol  replies  are
              stripped of meaning.

       -R reverse
              Consult  the  reverse  file via mk(1l) to search for the correct
              host based on the marker returned by gethostbyaddr(3) and the IP
              submarker  returned  by  getpeername(2).  When no name was found
              the marker will be commercial at (@).  The -s  and  -l0  options
              are set, as well as the name of the configuration file(s) speci-
              fied under -DCONFIGS=config.  When the reverse filename  is  dot
              (.)  then  the  specified  (-C  and  -Z) configuration files are
              searched.

              When the command exit(3)'s non-zero,  or  the  resulting  output
              contains  white-space,  or is zero length the client is notified
              that no such host exists.

       -V
              Show only the programs version information and exit.

       -x
              Trace replies from the remote service on stderr.

       -X ex-config
              Passed on to msrc, only 1 instance of this option is allowed.

       -Z zero-config
              Similarly to -X, this option  is  passed  on  to  mmsrc.   These
              options are often used to set the attribute macro MSRCMUX to the
              name of the RFC1078 service.  This allows msrc-driven MAP  files
              to  added  extra  features  to  generated  files.   For  example
              local/lib/hxmd's auto.cf adds more information  to  when  driven
              from the amazing mux.

ENVIRONMENT
       $CONFIGS
              A list of the absolute paths to all the msrc configuration files
              specified under -C and -Z (but not -X or any file  specified  by
              the client).

       $HXMD_LIB
              Set to the library directory specified as hxmd-libs under -L.

       $MK
              Set to "-sl0" to prevent mk from going interactive, or producing
              noise on stderr or stdout.

       $PATH
              We add /usr/local/sbin and /usr/local/bin to  the  search  path,
              because the default system path usually doesn't include these.

       $SHELL
              Set to /bin/sh. This allow mk(1l) to run correctly.

BUILDING
       Msrcmux  builds  an empty temporary directory (stage), then calls mmsrc
       to produce the tar output as:
            mmsrc -yINTO=stage -lDHOST=client -Cconfig -- tar cf - .
       That command is run from  msrc-root/msrc-dir,  which  should  have  the
       required recipe file and master copies of the source required.

       It  is  possible to hook into the process with -E's mmsrc specification
       to replace the default action with another.   For  example  the  script
       below runs gzip to compress the stream for the client:
            #!/bin/sh
            exec 0</dev/null
            mmsrc "$@" | gzip -7
            exit 0
       When configured in the tcpmux list as something like:
            zmmux stream tcp nowait source /usr/local/libexec/msrcmux msrcmux -Eabove msrc-root
       (where  above  is  the  path to the script above) clients may then pull
       their tar(1) archives with less network  bandwidth  by  requesting  the
       zmmux  service, and sending the output to gzip -dc before unpacking the
       archive.  The additional time spent compressing  each  archive  by  the
       service is usually negligible on a modern host.

       Similarly  the  stream  could be ciphered with a pre-shared key for the
       given host.  The client is  expected  to  understand  any  reply-format
       rules based on the name of the requested service.

       Adding  a zero-config to set MSRCMUX allows more checks or features for
       clients.    See    hxmd(8l)'s    auto.cf    for    an    example    (in
       /usr/local/lib/hxmd/auto.cf or in the source for that file).
            msrcmux stream tcp nowait source /usr/local/libexec/msrcmux msrcmux -Eabove -Zmux.zf msrc-root
       The default mux.zf file is also in hxmd's library directory.

EXAMPLES
       In  the  examples below the host "sulaco" holds the local master source
       repository.  Usually local site policy provides a CNAME for  the  host,
       so updated scripts don't hard-code a name that might change.

       muxcat sulaco msrcmux local/bin/oue site.cf >/tmp/oue.tar
              Ask  the  server  "sulaco"  for a platform copy of oue's source,
              produced with meta-information from site.cf with respect to  our
              host.  Unpack that archive to build the product.

       muxcat -x sulaco msrcmux Pkgs/msrc_base site.cf
              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.

       muxcat sulaco zmmux local/bin/oue . |gzip -dc |tar xf -
              Pull a compressed platform copy of oue from the server's default
              meta-configuration  file,  uncompress  it, and unpack it in this
              directory.

       msrcmux -h
              Output the standard help information, which includes the default
              values for the options with specifications.

       msrcmux -V
              The  standard  version  information includes the default path to
              the local master source repository.  This is  also  a  clue  for
              hostlint(8l).

MARKUP in reverse
       The  reverse  file  is  searched with mk(1), so we markup the file with
       lines to match either the hostname (as a marker) or the IP address  (as
       a submarker):

       # $*(127.0.0.1): hostname
              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 host-
              name(1).

       # $@(10.8.13.55): echo sulaco.npcguild.org
              The local domain's reverse for the sulaco reverses to  a  CNAME,
              patch it here to allow client updates by the FQDN.

       # $*(*): ${echo:-echo} %M
              Allow any machine we do not have a rule for to try the name msr-
              cmux found in the specified (or default) configuration file.

       # $*(*): exec %b %ol0 -m'%m' -d'%s' -e"$CONFIGS" /dev/null
              Try to chain to the  configuration  files  at  the  end  of  the
              reverse map.  This excludes the use of the previous example.

BUGS
       We  trust  some  files specified on the command line (reverse, configs,
       and zero-config) as we execute marked lines in these files.  We  assume
       that  options  configured  in  the  tcpmux entry are known to be secure
       files.

       We allow clients to specify any hxmd configuration file, from the local
       filesystem.   If  it  is possible to force a local master recipe to run
       any dangerous shell commands, then that's a bad idea.  In general it is
       not  possible to force a make(1) recipe to do anything really dangerous
       via host attributes.

AUTHORS
       Kevin S Braunsdorf, Npcguild.org
       msrc at ksb.npcguild.org.no-spam

SEE ALSO
       muxcat(1l), mmsrc(8l), mpull(8l), tcpmux(8l), mk(1l), tar(1),  gzip(1),
       getpeername(2),   dumpmux(8l),  muxcat(1l),  muxsend(1l),  recvmux(7l),
       tcpmux(8) or tcpmux(8l), inetd(8) or xinetd(8), oue(1l)



                                     LOCAL                          MSRCMUX(7)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | BUILDING | EXAMPLES | BUGS | AUTHORS | SEE ALSO