Added CCS authentication description.
[charm.git] / doc / converse / ccs.tex
1 \chapter{\converse{} Client-Server Interface}
2
3 This note describes the \converse{} client-server (CCS) 
4 module. This module enables \converse{} programs to act as
5 parallel servers, responding to requests from (non-\converse{}) programs
6 across the internet.
7
8 The CCS module is split into two parts-- client and server. 
9 The server side is the interface used by a \converse{} program;
10 the client side is used by arbitrary (non-\converse{}) programs.
11 The following sections describe both these parts. 
12
13 A CCS client accesses a running \converse{} program by talking to
14 a {\tt server-host}, which receives the CCS requests and relays them
15 to the appropriate processor.  The {\tt server-host} is \kw{charmrun}
16 for net- versions, and is the first processor for all other versions.
17
18
19 \section{CCS: Starting a Server}
20 A \converse{} program is started using
21 \begin{alltt}
22 charmrun pgmname +pN charmrun-opts pgm-opts
23 \end{alltt}
24 \kw{charmrun} also accepts the CCS options:
25
26 {\tt ++server}: open a CCS server on any TCP port number
27
28 {\tt ++server-port}=$port$: open the given TCP port as a CCS server   
29
30 {\tt ++server-auth}=$authfile$: accept authenticated queries
31
32 As the parallel job starts, it will print a line giving the 
33 IP address and TCP port number of the new CCS server.
34 The format is: ``ccs: Server IP = $ip$, Server port = $port$ \$'',
35 where $ip$ is a dotted decimal version of the 
36 server IP address, and $port$ is the decimal port number.
37
38 \section{CCS: Client-Side}
39
40 A CCS client connects to a CCS server, asks a server PE to 
41 execute a pre-registered handler, and receives the response data.
42 The CCS client may be written in any language (see CCS network protocol,
43 below), but a C interface (files ``ccs-client.c'' and ``ccs-client.h'') 
44 and Java interface (file ``CcsServer.java'') are available in 
45 the charm include directory.
46
47 The C routines use the skt\_abort error-reporting strategy;
48 see ``sockRoutines.h'' for details.  The C client API is:
49
50 \function{void CcsConnect(CcsServer *svr, char *host, int port);}
51 Connect to the given CCS server.  svr points to a pre-allocated
52 CcsServer structure.
53
54 \function{void CcsConnectIp(CcsServer *svr, int ip, int port);}
55 As above, but a numeric IP is specified.
56
57 \function{int CcsNumNodes(CcsServer *svr);}
58 \function{int CcsNumPes(CcsServer *svr);}
59 \function{int CcsNodeFirst(CcsServer *svr, int node);}
60 \function{int CcsNodeSize(CcsServer *svr,int node);}
61 These functions return information about the parallel machine;
62 they are equivalent to the \converse{} calls CmiNumNodes,
63 CmiNumPes, CmiNodeFirst, and CmiNodeSize.
64
65 \function{void CcsSendRequest(CcsServer *svr, char *hdlrID, int pe, 
66                     unsigned int size, const char *msg);}
67 Ask the server to execute the handler hdlrID on the given processor.
68 The handler is passed the given data as a message.  The data may
69 be in any desired format (including binary). 
70
71 \function{int CcsRecvResponse(CcsServer *svr, 
72                     unsigned int maxsize, char *recvBuffer, int timeout);}
73 Receive a response to the previous request in-place.
74 Timeout gives the number of seconds to wait before returning 0;
75 otherwise the number of bytes received is returned. 
76
77 \function{int CcsRecvResponseMsg(CcsServer *svr, 
78                     unsigned int *retSize,char **newBuf, int timeout);}
79 As above, but receive a variable-length response.  The
80 returned buffer must be free()'d after use.
81
82 \function{int CcsProbe(CcsServer *svr);}
83 Return 1 if a response is available; otherwise 0.
84
85 \function{void CcsFinalize(CcsServer *svr);}
86 Closes connection and releases server.
87
88
89 The Java routines throw an IOException on network errors.
90 Use javadoc on CcsServer.java for the interface, which mirrors
91 the C version above.
92
93
94 \section{CCS: Server-Side}
95
96 Once a request arrives on a CCS server socket, the CCS server 
97 runtime looks up the appropriate handler and calls it.
98 If no handler is found, the runtime prints a diagnostic
99 and ignores the message.
100
101 CCS calls its handlers in the usual \converse{} fashion--
102 the request data is passed as a newly-allocated message,
103 and the actual user data begins CmiMsgHeaderSizeBytes
104 into the message.  The handler is responsible for CmiFree'ing
105 the passed-in message.
106
107 The interface for the server side of CCS is included in 
108 ``converse.h''; if CCS is disabled (in conv-mach.h), all
109 CCS routines become macros returning 0.
110
111 The handler registration interface is:
112
113 \function{void CcsUseHandler(char *id, int hdlr);}
114 \function{int CcsRegisterHandler(char *id, CmiHandler fn);}
115 Associate this handler ID string with this function.  
116 hdlr is a \converse{} handler index; fn is a function pointer.
117 The ID string cannot be more than 32 characters, including the
118 terminating NULL.
119
120
121
122 These calls can be used from within a CCS handler:
123
124 \function{int CcsEnabled(void);}
125 Return 1 if CCS routines are available (from conv-mach.h).
126 This routine does not determine if a CCS server port is 
127 actually open.
128
129 \function{int CcsIsRemoteRequest(void);}
130 Return 1 if this handler was called via CCS; 0 if it was
131 called as the result of a normal \converse{} message.
132
133 \function{void CcsCallerId(skt\_ip\_t *pip, unsigned int *pport);}
134 Return the IP address and TCP port number
135 of the CCS client that invoked this method.
136 Can only be called from a CCS handler invoked remotely.
137
138 \function{void CcsSendReply(int size, const void *reply);}
139 Send the given data back to the client as a reply.
140 Can only be called from a CCS handler invoked remotely.
141
142 \function{CcsDelayedReply CcsDelayReply(void);}
143 Allows a CCS reply to be delayed until after the handler
144 has completed.  Returns a token used below.
145
146 \function{void CcsSendDelayedReply(CcsDelayedReply d,int size, const void *reply);}
147 Send a CCS reply for the given request.  Unlike
148 CcsSendReply, can be invoked from any handler on any processor.
149
150
151 \section{CCS: system handlers}
152 The CCS runtime system provides several built-in CCS handlers,
153 which are available in any \converse{} job:
154
155 \kw{ccs\_getinfo}
156 Takes an empty message, responds with information about the parallel
157 job.  The response is in the form of network byte order (big-endian) 4-byte 
158 integers: first the number of parallel nodes, then the number of processors
159 on each node.  This handler is invoked by the client routine CcsConnect.
160
161 \kw{ccs\_killport}
162 Allows a client to be notified when a parallel run exits (for any reason).
163 Takes one network byte order (big-endian) 4-byte integer: a TCP port
164 number. The runtime writes ``die\\n'' to this port before exiting.
165 There is no response data.
166
167 \kw{perf\_monitor}
168 Takes an empty message, responds (after a delay) with performance data.
169 When CMK\_WEB\_MODE is enabled in conv-mach.h, the runtime system collects
170 performance data.  Every 2 seconds, this data is collected on processor
171 0 and sent to any clients that have invoked perf\_monitor on processor 0.
172 The data is returned in ASCII format with the leading string "perf", 
173 and for each processor the current load (in percent) and scheduler message
174 queue length (in messages).  Thus a heavily loaded, two-processor system
175 might reply with the string ``perf 98 148230 100 385401''.
176
177
178 \section{CCS: network protocol}
179 This information is provided for completeness and clients written
180 in non-C, non-Java languages.  The client and server APIs above are
181 the preferred way to use CCS.
182
183 A CCS request arrives as a new TCP connection to the CCS server port.
184 The client speaks first, sending a request header and then the request
185 data.  The server then sends the response header and response data,
186 and closes the connection.  Numbers are sent as network byte order
187 (big-endian) 4-byte integers-- network binary integers.
188
189 The request header has three fields: the number of bytes of request data,
190 the (0-based) destination processor number, and the CCS handler identifier
191 string.  The byte count and processor are network binary integers (4 bytes
192 each), the CCS handler ID is zero-terminated ASCII text (32 bytes); for
193 a total request header length of 40 bytes.  The remaining request data
194 is passed directly to the CCS handler.
195
196 The response header consists of a single network binary integer-- the 
197 length in bytes of the response data to follow.  The header is thus 4 
198 bytes long.  If there is no response data, this field has value 0.
199
200
201 \section{CCS: Authentication}
202 By default, CCS provides no authentication-- this means any
203 client anywhere on the internet can interact with the server.
204 $authfile$, passed to '++server-auth', is a configuration file
205 that enables authentication and describes the authentication to 
206 perform.
207
208 The configuration file is line-oriented ASCII text,
209 consisting of security level / key pairs.  The security
210 level is an integer from 0 (the default) to 255.
211 Any security levels not listed in the file are disallowed.
212
213 The key is the 128-bit secret key used to authenticate CCS
214 clients for that security level.  It is either up 
215 to 32 hexadecimal digits of key data or the string "OTP".
216 "OTP" stands for One Time Pad, which will generate a random
217 key when the server is started.  This key is printed out
218 at job startup with the format "CCS\_OTP\_KEY$>$ Level $i$ key: $hexdigits$"
219 where $i$ is the security level in decimal and $hexdigits$ is
220 32 hexadecimal digits of key data.
221
222 For example, a valid CCS authentication file might consist of
223 the single line "0 OTP", indicating that the default security
224 level 0 requires a randomly generated key.  All other security
225 levels are disallowed.
226
227