1This is Info file cvsclient.info, produced by Makeinfo version 1.67 2from the input file ../../work/ccvs/doc/cvsclient.texi. 3 4 5File: cvsclient.info, Node: Top, Next: Introduction, Up: (dir) 6 7CVS Client/Server 8***************** 9 10 This document describes the client/server protocol used by CVS. It 11does not describe how to use or administer client/server CVS; see the 12regular CVS manual for that. This is version 1.10.5 of the protocol 13specification--*Note Introduction::, for more on what this version 14number means. 15 16* Menu: 17 18* Introduction:: What is CVS and what is the client/server protocol for? 19* Goals:: Basic design decisions, requirements, scope, etc. 20* Connection and Authentication:: Various ways to connect to the server 21* Password scrambling:: Scrambling used by pserver 22* Protocol:: Complete description of the protocol 23* Protocol Notes:: Possible enhancements, limitations, etc. of the protocol 24 25 26File: cvsclient.info, Node: Introduction, Next: Goals, Prev: Top, Up: Top 27 28Introduction 29************ 30 31 CVS is a version control system (with some additional configuration 32management functionality). It maintains a central "repository" which 33stores files (often source code), including past versions, information 34about who modified them and when, and so on. People who wish to look 35at or modify those files, known as "developers", use CVS to "check out" 36a "working directory" from the repository, to "check in" new versions 37of files to the repository, and other operations such as viewing the 38modification history of a file. If developers are connected to the 39repository by a network, particularly a slow or flaky one, the most 40efficient way to use the network is with the CVS-specific protocol 41described in this document. 42 43 Developers, using the machine on which they store their working 44directory, run the CVS "client" program. To perform operations which 45cannot be done locally, it connects to the CVS "server" program, which 46maintains the repository. For more information on how to connect see 47*Note Connection and Authentication::. 48 49 This document describes the CVS protocol. Unfortunately, it does not 50yet completely document one aspect of the protocol--the detailed 51operation of each CVS command and option--and one must look at the CVS 52user documentation, `cvs.texinfo', for that information. The protocol 53is non-proprietary (anyone who wants to is encouraged to implement it) 54and an implementation, known as CVS, is available under the GNU Public 55License. The CVS distribution, containing this implementation, 56`cvs.texinfo', and a copy (possibly more or less up to date than what 57you are reading now) of this document, `cvsclient.texi', can be found 58at the usual GNU FTP sites, with a filename such as 59`cvs-VERSION.tar.gz'. 60 61 This is version 1.10.5 of the protocol specification. This version 62number is intended only to aid in distinguishing different versions of 63this specification. Although the specification is currently maintained 64in conjunction with the CVS implementation, and carries the same 65version number, it also intends to document what is involved with 66interoperating with other implementations (such as other versions of 67CVS); see *Note Requirements::. This version number should not be used 68by clients or servers to determine what variant of the protocol to 69speak; they should instead use the `valid-requests' and 70`Valid-responses' mechanism (*note Protocol::.), which is more flexible. 71 72 73File: cvsclient.info, Node: Goals, Next: Connection and Authentication, Prev: Introduction, Up: Top 74 75Goals 76***** 77 78 * Do not assume any access to the repository other than via this 79 protocol. It does not depend on NFS, rdist, etc. 80 81 * Providing a reliable transport is outside this protocol. The 82 protocol expects a reliable transport that is transparent (that 83 is, there is no translation of characters, including characters 84 such as such as linefeeds or carriage returns), and can transmit 85 all 256 octets (for example for proper handling of binary files, 86 compression, and encryption). The encoding of characters 87 specified by the protocol (the names of requests and so on) is the 88 invariant ISO 646 character set (a subset of most popular 89 character sets including ASCII and others). For more details on 90 running the protocol over the TCP reliable transport, see *Note 91 Connection and Authentication::. 92 93 * Security and authentication are handled outside this protocol (but 94 see below about `cvs kserver' and `cvs pserver'). 95 96 * The protocol makes it possible for updates to be atomic with 97 respect to checkins; that is if someone commits changes to several 98 files in one cvs command, then an update by someone else would 99 either get all the changes, or none of them. The current CVS 100 server can't do this, but that isn't the protocol's fault. 101 102 * The protocol is, with a few exceptions, transaction-based. That 103 is, the client sends all its requests (without waiting for server 104 responses), and then waits for the server to send back all 105 responses (without waiting for further client requests). This has 106 the advantage of minimizing network turnarounds and the 107 disadvantage of sometimes transferring more data than would be 108 necessary if there were a richer interaction. Another, more 109 subtle, advantage is that there is no need for the protocol to 110 provide locking for features such as making checkins atomic with 111 respect to updates. Any such locking can be handled entirely by 112 the server. A good server implementation (such as the current CVS 113 server) will make sure that it does not have any such locks in 114 place whenever it is waiting for communication with the client; 115 this prevents one client on a slow or flaky network from 116 interfering with the work of others. 117 118 * It is a general design goal to provide only one way to do a given 119 operation (where possible). For example, implementations have no 120 choice about whether to terminate lines with linefeeds or some 121 other character(s), and request and response names are 122 case-sensitive. This is to enhance interoperability. If a 123 protocol allows more than one way to do something, it is all too 124 easy for some implementations to support only some of them 125 (perhaps accidentally). 126 127 128File: cvsclient.info, Node: Connection and Authentication, Next: Password scrambling, Prev: Goals, Up: Top 129 130How to Connect to and Authenticate Oneself to the CVS server 131************************************************************ 132 133 Connection and authentication occurs before the CVS protocol itself 134is started. There are several ways to connect. 135 136server 137 If the client has a way to execute commands on the server, and 138 provide input to the commands and output from them, then it can 139 connect that way. This could be the usual rsh (port 514) 140 protocol, Kerberos rsh, SSH, or any similar mechanism. The client 141 may allow the user to specify the name of the server program; the 142 default is `cvs'. It is invoked with one argument, `server'. 143 Once it invokes the server, the client proceeds to start the cvs 144 protocol. 145 146kserver 147 The kerberized server listens on a port (in the current 148 implementation, by having inetd call "cvs kserver") which defaults 149 to 1999. The client connects, sends the usual kerberos 150 authentication information, and then starts the cvs protocol. 151 Note: port 1999 is officially registered for another use, and in 152 any event one cannot register more than one port for CVS, so 153 GSS-API (see below) is recommended instead of kserver as a way to 154 support kerberos. 155 156pserver 157 The name "pserver" is somewhat confusing. It refers to both a 158 generic framework which allows the CVS protocol to support several 159 authentication mechanisms, and a name for a specific mechanism 160 which transfers a username and a cleartext password. Servers need 161 not support all mechanisms, and in fact servers will typically 162 want to support only those mechanisms which meet the relevant 163 security needs. 164 165 The pserver server listens on a port (in the current 166 implementation, by having inetd call "cvs pserver") which defaults 167 to 2401 (this port is officially registered). The client 168 connects, and sends the following: 169 170 * the string `BEGIN AUTH REQUEST', a linefeed, 171 172 * the cvs root, a linefeed, 173 174 * the username, a linefeed, 175 176 * the password trivially encoded (see *Note Password 177 scrambling::), a linefeed, 178 179 * the string `END AUTH REQUEST', and a linefeed. 180 181 The client must send the identical string for cvs root both here 182 and later in the `Root' request of the cvs protocol itself. 183 Servers are encouraged to enforce this restriction. The possible 184 server responses (each of which is followed by a linefeed) are the 185 following. Note that although there is a small similarity between 186 this authentication protocol and the cvs protocol, they are 187 separate. 188 189 `I LOVE YOU' 190 The authentication is successful. The client proceeds with 191 the cvs protocol itself. 192 193 `I HATE YOU' 194 The authentication fails. After sending this response, the 195 server may close the connection. It is up to the server to 196 decide whether to give this response, which is generic, or a 197 more specific response using `E' and/or `error'. 198 199 `E TEXT' 200 Provide a message for the user. After this reponse, the 201 authentication protocol continues with another response. 202 Typically the server will provide a series of `E' responses 203 followed by `error'. Compatibility note: CVS 1.9.10 and 204 older clients will print `unrecognized auth response' and 205 TEXT, and then exit, upon receiving this response. 206 207 `error CODE TEXT' 208 The authentication fails. After sending this response, the 209 server may close the connection. The CODE is a code 210 describing why it failed, intended for computer consumption. 211 The only code currently defined is `0' which is nonspecific, 212 but clients must silently treat any unrecognized codes as 213 nonspecific. The TEXT should be supplied to the user. 214 Compatibility note: CVS 1.9.10 and older clients will print 215 `unrecognized auth response' and TEXT, and then exit, upon 216 receiving this response. 217 218 If the client wishes to merely authenticate without starting the 219 cvs protocol, the procedure is the same, except BEGIN AUTH REQUEST 220 is replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST is 221 replaced with END VERIFICATION REQUEST, and upon receipt of I LOVE 222 YOU the connection is closed rather than continuing. 223 224 Another mechanism is GSSAPI authentication. GSSAPI is a generic 225 interface to security services such as kerberos. GSSAPI is 226 specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI 227 version 1); we are not aware of differences between the two which 228 affect the protocol in incompatible ways, so we make no attempt to 229 specify one version or the other. The procedure here is to start 230 with `BEGIN GSSAPI REQUEST'. GSSAPI authentication information is 231 then exchanged between the client and the server. Each packet of 232 information consists of a two byte big endian length, followed by 233 that many bytes of data. After the GSSAPI authentication is 234 complete, the server continues with the responses described above 235 (`I LOVE YOU', etc.). 236 237future possibilities 238 There are a nearly unlimited number of ways to connect and 239 authenticate. One might want to allow access based on IP address 240 (similar to the usual rsh protocol but with different/no 241 restrictions on ports < 1024), to adopt mechanisms such as 242 Pluggable Authentication Modules (PAM), to allow users to run 243 their own servers under their own usernames without root access, 244 or any number of other possibilities. The way to add future 245 mechanisms, for the most part, should be to continue to use port 246 2401, but to use different strings in place of `BEGIN AUTH 247 REQUEST'. 248 249 250File: cvsclient.info, Node: Password scrambling, Next: Protocol, Prev: Connection and Authentication, Up: Top 251 252Password scrambling algorithm 253***************************** 254 255 The pserver authentication protocol, as described in *Note 256Connection and Authentication::, trivially encodes the passwords. This 257is only to prevent inadvertent compromise; it provides no protection 258against even a relatively unsophisticated attacker. For comparison, 259HTTP Basic Authentication (as described in RFC2068) uses BASE64 for a 260similar purpose. CVS uses its own algorithm, described here. 261 262 The scrambled password starts with `A', which serves to identify the 263scrambling algorithm in use. After that follows a single octet for 264each character in the password, according to a fixed encoding. The 265values are shown here, with the encoded values in decimal. Control 266characters, space, and characters outside the invariant ISO 646 267character set are not shown; such characters are not recommended for use 268in passwords. There is a long discussion of character set issues in 269*Note Protocol Notes::. 270 271 0 111 P 125 p 58 272 ! 120 1 52 A 57 Q 55 a 121 q 113 273 " 53 2 75 B 83 R 54 b 117 r 32 274 3 119 C 43 S 66 c 104 s 90 275 4 49 D 46 T 124 d 101 t 44 276 % 109 5 34 E 102 U 126 e 100 u 98 277 & 72 6 82 F 40 V 59 f 69 v 60 278 ' 108 7 81 G 89 W 47 g 73 w 51 279 ( 70 8 95 H 38 X 92 h 99 x 33 280 ) 64 9 65 I 103 Y 71 i 63 y 97 281 * 76 : 112 J 45 Z 115 j 94 z 62 282 + 67 ; 86 K 50 k 93 283 , 116 < 118 L 42 l 39 284 - 74 = 110 M 123 m 37 285 . 68 > 122 N 91 n 61 286 / 87 ? 105 O 35 _ 56 o 48 287 288 289File: cvsclient.info, Node: Protocol, Next: Protocol Notes, Prev: Password scrambling, Up: Top 290 291The CVS client/server protocol 292****************************** 293 294 In the following, `\n' refers to a linefeed and `\t' refers to a 295horizontal tab; "requests" are what the client sends and "responses" 296are what the server sends. In general, the connection is governed by 297the client--the server does not send responses without first receiving 298requests to do so; see *Note Response intro:: for more details of this 299convention. 300 301 It is typical, early in the connection, for the client to transmit a 302`Valid-responses' request, containing all the responses it supports, 303followed by a `valid-requests' request, which elicits from the server a 304`Valid-requests' response containing all the requests it understands. 305In this way, the client and server each find out what the other 306supports before exchanging large amounts of data (such as file 307contents). 308 309* Menu: 310 311 312General protocol conventions: 313 314* Entries Lines:: Transmitting RCS data 315* File Modes:: Read, write, execute, and possibly more... 316* Filenames:: Conventions regarding filenames 317* File transmissions:: How file contents are transmitted 318* Strings:: Strings in various requests and responses 319* Dates:: Times and dates 320 321The protocol itself: 322 323* Request intro:: General conventions relating to requests 324* Requests:: List of requests 325* Response intro:: General conventions relating to responses 326* Response pathnames:: The "pathname" in responses 327* Responses:: List of responses 328* Text tags:: More details about the MT response 329 330An example session, and some further observations: 331 332* Example:: A conversation between client and server 333* Requirements:: Things not to omit from an implementation 334* Obsolete:: Former protocol features 335 336 337File: cvsclient.info, Node: Entries Lines, Next: File Modes, Up: Protocol 338 339Entries Lines 340============= 341 342 Entries lines are transmitted as: 343 344 / NAME / VERSION / CONFLICT / OPTIONS / TAG_OR_DATE 345 346 TAG_OR_DATE is either `T' TAG or `D' DATE or empty. If it is 347followed by a slash, anything after the slash shall be silently ignored. 348 349 VERSION can be empty, or start with `0' or `-', for no user file, 350new user file, or user file to be removed, respectively. 351 352 CONFLICT, if it starts with `+', indicates that the file had 353conflicts in it. The rest of CONFLICT is `=' if the timestamp matches 354the file, or anything else if it doesn't. If CONFLICT does not start 355with a `+', it is silently ignored. 356 357 OPTIONS signifies the keyword expansion options (for example `-ko'). 358In an `Entry' request, this indicates the options that were specified 359with the file from the previous file updating response (*note Response 360intro::., for a list of file updating responses); if the client is 361specifying the `-k' or `-A' option to `update', then it is the server 362which figures out what overrides what. 363 364 365File: cvsclient.info, Node: File Modes, Next: Filenames, Prev: Entries Lines, Up: Protocol 366 367File Modes 368========== 369 370 A mode is any number of repetitions of 371 372 MODE-TYPE = DATA 373 374 separated by `,'. 375 376 MODE-TYPE is an identifier composed of alphanumeric characters. 377Currently specified: `u' for user, `g' for group, `o' for other (see 378below for discussion of whether these have their POSIX meaning or are 379more loose). Unrecognized values of MODE-TYPE are silently ignored. 380 381 DATA consists of any data not containing `,', `\0' or `\n'. For 382`u', `g', and `o' mode types, data consists of alphanumeric characters, 383where `r' means read, `w' means write, `x' means execute, and 384unrecognized letters are silently ignored. 385 386 The two most obvious ways in which the mode matters are: (1) is it 387writeable? This is used by the developer communication features, and 388is implemented even on OS/2 (and could be implemented on DOS), whose 389notion of mode is limited to a readonly bit. (2) is it executable? 390Unix CVS users need CVS to store this setting (for shell scripts and 391the like). The current CVS implementation on unix does a little bit 392more than just maintain these two settings, but it doesn't really have 393a nice general facility to store or version control the mode, even on 394unix, much less across operating systems with diverse protection 395features. So all the ins and outs of what the mode means across 396operating systems haven't really been worked out (e.g. should the VMS 397port use ACLs to get POSIX semantics for groups?). 398 399 400File: cvsclient.info, Node: Filenames, Next: File transmissions, Prev: File Modes, Up: Protocol 401 402Conventions regarding transmission of file names 403================================================ 404 405 In most contexts, `/' is used to separate directory and file names 406in filenames, and any use of other conventions (for example, that the 407user might type on the command line) is converted to that form. The 408only exceptions might be a few cases in which the server provides a 409magic cookie which the client then repeats verbatim, but as the server 410has not yet been ported beyond unix, the two rules provide the same 411answer (and what to do if future server ports are operating on a 412repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been carefully 413thought out). 414 415 Characters outside the invariant ISO 646 character set should be 416avoided in filenames. This restriction may need to be relaxed to allow 417for characters such as `[' and `]' (see above about non-unix servers); 418this has not been carefully considered (and currently implementations 419probably use whatever character sets that the operating systems they 420are running on allow, and/or that users specify). Of course the most 421portable practice is to restrict oneself further, to the POSIX portable 422filename character set as specified in POSIX.1. 423 424 425File: cvsclient.info, Node: File transmissions, Next: Strings, Prev: Filenames, Up: Protocol 426 427File transmissions 428================== 429 430 File contents (noted below as FILE TRANSMISSION) can be sent in one 431of two forms. The simpler form is a number of bytes, followed by a 432linefeed, followed by the specified number of bytes of file contents. 433These are the entire contents of the specified file. Second, if both 434client and server support `gzip-file-contents', a `z' may precede the 435length, and the `file contents' sent are actually compressed with 436`gzip' (RFC1952/1951) compression. The length specified is that of the 437compressed version of the file. 438 439 In neither case are the file content followed by any additional data. 440The transmission of a file will end with a linefeed iff that file (or 441its compressed form) ends with a linefeed. 442 443 The encoding of file contents depends on the value for the `-k' 444option. If the file is binary (as specified by the `-kb' option in the 445appropriate place), then it is just a certain number of octets, and the 446protocol contributes nothing towards determining the encoding (using 447the file name is one widespread, if not universally popular, mechanism). 448If the file is text (not binary), then the file is sent as a series of 449lines, separated by linefeeds. If the keyword expansion is set to 450something other than `-ko', then it is expected that the file conform 451to the RCS expectations regarding keyword expansion--in particular, 452that it is in a character set such as ASCII in which 0x24 is a dollar 453sign (`$'). 454 455 456File: cvsclient.info, Node: Strings, Next: Dates, Prev: File transmissions, Up: Protocol 457 458Strings 459======= 460 461 In various contexts, for example the `Argument' request and the `M' 462response, one transmits what is essentially an arbitrary string. Often 463this will have been supplied by the user (for example, the `-m' option 464to the `ci' request). The protocol has no mechanism to specify the 465character set of such strings; it would be fairly safe to stick to the 466invariant ISO 646 character set but the existing practice is probably 467to just transmit whatever the user specifies, and hope that everyone 468involved agrees which character set is in use, or sticks to a common 469subset. 470 471 472File: cvsclient.info, Node: Dates, Next: Request intro, Prev: Strings, Up: Protocol 473 474Dates 475===== 476 477 The protocol contains times and dates in various places. 478 479 For the `-D' option to the `annotate', `co', `diff', `export', 480`history', `rdiff', `rtag', `tag', and `update' requests, the server 481should support two formats: 482 483 26 May 1997 13:01:40 -0000 ; RFC 822 as modified by RFC 1123 484 5/26/1997 13:01:40 GMT ; traditional 485 486 The former format is preferred; the latter however is sent by the CVS 487command line client (versions 1.5 through at least 1.9). 488 489 For the `-d' option to the `log' request, servers should at least 490support RFC 822/1123 format. Clients are encouraged to use this format 491too (traditionally the command line CVS client has just passed along 492the date format specified by the user, however). 493 494 The `Mod-time' response and `Checkin-time' request use RFC 822/1123 495format (see the descriptions of that response and request for details). 496 497 For `Notify', see the description of that request. 498 499 500File: cvsclient.info, Node: Request intro, Next: Requests, Prev: Dates, Up: Protocol 501 502Request intro 503============= 504 505 By convention, requests which begin with a capital letter do not 506elicit a response from the server, while all others do - save one. The 507exception is `gzip-file-contents'. Unrecognized requests will always 508elicit a response from the server, even if that request begins with a 509capital letter. 510 511