diff options
Diffstat (limited to 'man/8/collabsrv')
| -rw-r--r-- | man/8/collabsrv | 334 |
1 files changed, 334 insertions, 0 deletions
diff --git a/man/8/collabsrv b/man/8/collabsrv new file mode 100644 index 00000000..43939187 --- /dev/null +++ b/man/8/collabsrv @@ -0,0 +1,334 @@ +.TH COLLABSRV 8 +.SH NAME +collabsrv \- multi-user collaboration +.SH SYNOPSIS +.B collabsrv/collabsrv +[ +.BI "-f " keyfile +] [ +.BI "-n " netaddress +] [ +.I dir +] +.PP +.B collabsrv/servers/chatsrv +.PP +.B collabsrv/servers/mpx +.PP +.B collabsrv/servers/wbsrv +.SH DESCRIPTION +.I Collabsrv +listens on network address +.I netaddress +(default: +.BR tcp!*!9999 ) +for incoming requests to attach to services +it offers. +The services are defined by the contents of directory +.IR dir +(default: +.BR /services/collab ). +.I Collabsrv +serves an authenticated Styx connection that exports the contents of +.IB dir /export +(default: +.BR /services/collab/export ). +The exported name space can contain directories from a shared file server, +but it will also contain a directory +.B services +giving access to any collaborative activity services that have been configured. +.PP +The +.B services +directory contains a single +.B ctl +file and a set of subdirectories, numbered +.BR 0 , +.BR 1 +and so on. +The +.B 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. +.PP +A client wishing to make use of the services must first +.IR sys-dial (2) +to connect to +.IR collabsrv, +and authenticate and mount the resulting Styx connection. +It can do so using the +.I mount +command +(see +.IR bind (1)), +or by +using +.IR security-auth (2) +and +.B Sys->mount +(see +.IR sys-bind (2)). +Normally, this is done by +.IR collab (1). +.PP +A new connection to a particular service is requested by opening the +.B ctl +file for reading and writing, +writing a service request to it, and reading back +the number of the directory corresponding to the requested service. +A service request written to +.B ctl +is text of the following form: +.IP +.DS +.I "service id" +.DE +.PP +where +.I service +is a string specifying the type of service (eg, +.BR chat ) +and +.I id +is a string identifying the instance. +The server does not interpret +.IR id ; +it is up to the clients to agree a naming convention (often +using the name of a shared file as an +.IR id ). +.I Collabsrv +will connect to instance +.I id +of the requested +.I 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 +.BR ctl , +a read will return the number of the service +directory containing the client's private connection to that service instance. +Closing the +.B ctl +file disconnects from the service. +.PP +Available services are defined by a configuration file +.BR /services/collab/services.cfg , +which contains a sequence of configuration +entries of the following form: +.IP +.EX +.I service +.br +\f5 path=\fIdisfile\fP +.EE +.PP +where +.I service +is the name presented in a service request, and +.I disfile +names a Dis file implementing that service; +path names are interpreted relative to +.BR /services/collab , +but usually refer to files in +.BR /dis/collabsrv/servers . +.PP +Each +.I collabsrv +service is represented by a name space peculiar to that service. +The interface to the service is therefore implemented by a service-specific Styx server +.RI ( disfile +in the configuration file). +Current services are described below. +.SS "Chat" +.I 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: +.TF users +.TP +.B users +A read-only file that lists the user names of the current members of the group, one per line. +The version number of the file's Qid +(see +.IR sys-stat (2)) +is incremented each time a client arrives or leaves. +.TP +.B msgs +.RS +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 message, prefixed by the name of the sender, +or +.B <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 messages are generated by the server: +.IP +.EX ++++ \fIname\fP has arrived +--- \fIname\fP has left +.EE +.PP +as clients come and go. +.RE +.SS "Multiplexor" +.I 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: +.TF users +.TP +.B root +An exclusive-use file read and written by the root process +to communicate with the leaf processes. +.TP +.B leaf +Client processes read and write this file to communicate with the +root process (each +.B open +of +.B leaf +is independent). +It cannot be opened until a process has opened +.BR root . +After +.B root +has been closed, and any remaining messages on +.B leaf +have been read, +subsequent reads will return zero bytes (end-of-file). +.TP +.B users +A read-only text file that lists the user names of processes that currently have +.B leaf +open. +There is one line per leaf, containing a unique numeric ID for the leaf, a space, and then the users's name. +.PP +A message written to +.B root +is replicated on all instances of +.B leaf +that are currently open. +A message written to any instance of +.B leaf +will be read by the process reading +.BR root . +Data written to both +.B root +and +.B leaf +has a prefix added to identify the sender, causing messages +to have the following format: +.IP +.EX +.I "seq clientid op name data" +.EE +.PP +where +.I seq +is a unique message sequence number; +.I clientid +is a unique number identifying the process amongst currently connected clients, +with 0 identifying the root process; +.I op +is a single character giving the message type (see below); +.I name +is the sending process's user name; and +.I data +is the data written by the process, which can be text or binary (the message header is always text). +.I Mpx +also generates messages as root and leaf processes arrive and leave. +These are identified by +.IR op . +The various +.I op +values and the direction in which they can occur are listed below: +.TP +.B a +New leaf process has arrived (leaf to root) +.TP +.B M +Message from root process (root to leaf) +.TP +.B m +Message from leaf process (leaf to root) +.TP +.B L +Root process has left (root to leaf) +.TP +.B l +Leaf process has left (leaf to root) +.PP +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 +.B poll +and +.B poller +in +.IR collab-clients (1)), +but could be used for several other services, such as auctions. +.SS "Whiteboard" +.I Wbsrv +offers a service for sharing a simple line drawing. +It serves two files: +.TP +.B wb.bit +A read-only file containing an uncompressed +.IR image (6) +with the current state of the drawing. +.TP +.B strokes +This file is read and written to exchange strokes with other clients. +A stroke has the following representation: +.RS +.IP +.IR "colour width x0 y0 x1 y1 " ... +.PP +where all values are space-separated decimal numbers: +.I colour +is an index into the +.IR rgbv (6) +colour map; +.I 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. +.RE +.PP +A whiteboard client should read the +.B wb.bit +file to obtain its image, then read the +.B strokes +file for instructions to keep it up to date. +.SH FILES +.TF /services/collab/export/services +.TP +.B /services/collab/export/services +active service directory +.TP +.B /services/collab/services.cfg +maps service names to modules +.TP +.B /dis/collabsrv/servers +service implementation modules +.SH SOURCE +.B /appl/collabsrv +.br +.B /appl/collabsrv/servers +.br +.B /appl/collabsrv/lib +.SH SEE ALSO +.IR collab (1), +.IR collab-clients (1) |