COLLABSRV(8)                                         COLLABSRV(8)

     NAME
          collabsrv - multi-user collaboration

     SYNOPSIS
          collab/collabsrv [ -f keyfile ] [ -n netaddress ] [ dir ]

          collab/servers/chatsrv

          collab/servers/mpx

          collab/servers/wbsrv

     DESCRIPTION
          Collabsrv listens on network address netaddress (default:
          tcp!*!9999) for incoming requests to attach to services it
          offers.  The services are defined by the contents of direc-
          tory dir (default: /services/collab).  Collabsrv serves an
          authenticated 9P connection that exports the contents of
          dir/export (default: /services/collab/export).  The exported
          name space can contain directories from a shared file
          server, but it will also contain a directory services giving
          access to any collaborative activity services that have been
          configured.

          The services directory contains a single ctl file and a set
          of subdirectories, numbered 0, 1 and so on.  The ctl is used
          to activate and access services.  Each service instance is
          identified by a name; clients connect to a given instance by
          presenting its name.  Each directory represents one instance
          of a service.  Each service instance corresponds to a name
          space; the clients all share that name space.  The name
          space is determined by the service.

          A client wishing to make use of the services must first
          dial(2) to connect to collabsrv, and authenticate and mount
          the resulting 9P connection.  It can do so using the mount
          command (see bind(1)), or by using security-auth(2) and
          Sys->mount (see sys-bind(2)). Normally, this is done by
          collab(1).

          A new connection to a particular service is requested by
          opening the ctl file for reading and writing, writing a ser-
          vice request to it, and reading back the number of the
          directory corresponding to the requested service.  A service
          request written to ctl is text of the following form:

               service id

          where service is a string specifying the type of service
          (eg, chat) and id is a string identifying the instance.  The

     Page 1                       Plan 9             (printed 3/29/24)

     COLLABSRV(8)                                         COLLABSRV(8)

          server does not interpret id; it is up to the clients to
          agree a naming convention (often using the name of a shared
          file as an id). Collabsrv will connect to instance id of the
          requested service type if one is already running, or start
          one if necessary; the write request returns an error if the
          service cannot be started.  Following a successful write to
          ctl, a read will return the number of the service directory
          containing the client's private connection to that service
          instance.  Closing the ctl file disconnects from the ser-
          vice.

          Available services are defined by a configuration file
          /services/collab/services.cfg, which contains a sequence of
          configuration entries of the following form:

               service
                    path=disfile

          where service is the name presented in a service request,
          and disfile names a Dis file implementing that service; path
          names are interpreted relative to /services/collab, but usu-
          ally refer to files in /dis/collab/servers.

          Each collabsrv service is represented by a name space pecu-
          liar to that service.  The interface to the service is
          therefore implemented by a service-specific 9P server
          (disfile in the configuration file).  Current services are
          described below.

        Chat
          Chatsrv provides a simple service for the exchange of text
          messages.  It serves a name space containing two files.  The
          files together represent a single messaging group:

          users  A read-only file that lists the user names of the
                 current members of the group, one per line.  The ver-
                 sion number of the file's Qid (see sys-stat(2)) is
                 incremented each time a client arrives or leaves.
          msgs
                 A client connects to the messaging group by opening
                 this file.  A message is sent to the group by writing
                 to the file.  Each read returns the next unread mes-
                 sage, prefixed by the name of the sender, or <you>
                 for a message sent by the current client.  A client
                 sees no messages sent before it connects.  Messages
                 are delivered in the same order to all clients;
                 clients receive their own messages.  Two special mes-
                 sages are generated by the server:
                      +++ name has arrived
                      --- name has left
                 as clients come and go.

     Page 2                       Plan 9             (printed 3/29/24)

     COLLABSRV(8)                                         COLLABSRV(8)

        Multiplexor
          Mpx offers a general fan-out/fan-in multiplexing service for
          a tree of processes, with one controlling or root process at
          the root of the tree, and a set of client processes at the
          leaves of the tree.  It serves three files:

          root   An exclusive-use file read and written by the root
                 process to communicate with the leaf processes.
          leaf   Client processes read and write this file to communi-
                 cate with the root process (each open of leaf is
                 independent).  It cannot be opened until a process
                 has opened root.  After root has been closed, and any
                 remaining messages on leaf have been read, subsequent
                 reads will return zero bytes (end-of-file).
          users  A read-only text file that lists the user names of
                 processes that currently have leaf open.  There is
                 one line per leaf, containing a unique numeric ID for
                 the leaf, a space, and then the users's name.
          A message written to root is replicated on all instances of
          leaf that are currently open.  A message written to any
          instance of leaf will be read by the process reading root.
          Data written to both root and leaf has a prefix added to
          identify the sender, causing messages to have the following
          format:
               seq clientid op name data
          where seq is a unique message sequence number; clientid is a
          unique number identifying the process amongst currently con-
          nected clients, with 0 identifying the root process; op is a
          single character giving the message type (see below); name
          is the sending process's user name; and data is the data
          written by the process, which can be text or binary (the
          message header is always text).  Mpx also generates messages
          as root and leaf processes arrive and leave.  These are
          identified by op. The various op values and the direction in
          which they can occur are listed below:
          a    New leaf process has arrived (leaf to root)
          M    Message from root process (root to leaf)
          m    Message from leaf process (leaf to root)
          L    Root process has left (root to leaf)
          l    Leaf process has left (leaf to root)
          Messages are only ever sent from the root to all leaves, or
          from a leaf to the root, never from leaf to leaf; the root
          process could of course rebroadcast a message from a leaf.
          The multiplexor service is used to implement a real-time
          poll (see poll and poller in collab-clients(1)), but could
          be used for several other services, such as auctions.

        Whiteboard
          Wbsrv offers a service for sharing a simple line drawing.
          It serves two files:

          wb.bit

     Page 3                       Plan 9             (printed 3/29/24)

     COLLABSRV(8)                                         COLLABSRV(8)

               A read-only file containing an uncompressed image(6)
               with the current state of the drawing.

          strokes
               This file is read and written to exchange strokes with
               other clients.  A stroke has the following representa-
               tion:

                    colour width x0 y0 x1 y1 ...

               where all values are space-separated decimal numbers:
               colour is an index into the rgbv(6) colour map; width
               is the width of the line in pixels, and the sequence of
               coordinate pairs defines the connected line segments to
               draw.  A stroke is transmitted from one client to all
               others by writing a stroke description to the file in a
               single write.  Each read returns a description of a
               stroke made by another client.

          A whiteboard client should read the wb.bit file to obtain
          its image, then read the strokes file for instructions to
          keep it up to date.

     FILES
          /services/collab/export/services  active service directory
          /services/collab/services.cfg     maps service names to mod-
                                            ules
          /dis/collab/servers               service implementation
                                            modules

     SOURCE
          /appl/collabsrv
          /appl/collab/servers
          /appl/collab/lib

     SEE ALSO
          collab(1), collab-clients(1)

     Page 4                       Plan 9             (printed 3/29/24)