1This is cvsclient.info, produced by Makeinfo version 3.12f from 2./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.7 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.7 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. Note that TEXT for this response, 217 or the TEXT in an `E' response, is not designed for machine 218 parsing. More vigorous use of CODE, or future extensions, 219 will be needed to prove a cleaner machine-parseable 220 indication of what the error was. 221 222 If the client wishes to merely authenticate without starting the 223 cvs protocol, the procedure is the same, except BEGIN AUTH REQUEST 224 is replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST is 225 replaced with END VERIFICATION REQUEST, and upon receipt of I LOVE 226 YOU the connection is closed rather than continuing. 227 228 Another mechanism is GSSAPI authentication. GSSAPI is a generic 229 interface to security services such as kerberos. GSSAPI is 230 specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI 231 version 1); we are not aware of differences between the two which 232 affect the protocol in incompatible ways, so we make no attempt to 233 specify one version or the other. The procedure here is to start 234 with `BEGIN GSSAPI REQUEST'. GSSAPI authentication information is 235 then exchanged between the client and the server. Each packet of 236 information consists of a two byte big endian length, followed by 237 that many bytes of data. After the GSSAPI authentication is 238 complete, the server continues with the responses described above 239 (`I LOVE YOU', etc.). 240 241future possibilities 242 There are a nearly unlimited number of ways to connect and 243 authenticate. One might want to allow access based on IP address 244 (similar to the usual rsh protocol but with different/no 245 restrictions on ports < 1024), to adopt mechanisms such as 246 Pluggable Authentication Modules (PAM), to allow users to run 247 their own servers under their own usernames without root access, 248 or any number of other possibilities. The way to add future 249 mechanisms, for the most part, should be to continue to use port 250 2401, but to use different strings in place of `BEGIN AUTH 251 REQUEST'. 252 253 254File: cvsclient.info, Node: Password scrambling, Next: Protocol, Prev: Connection and Authentication, Up: Top 255 256Password scrambling algorithm 257***************************** 258 259 The pserver authentication protocol, as described in *Note 260Connection and Authentication::, trivially encodes the passwords. This 261is only to prevent inadvertent compromise; it provides no protection 262against even a relatively unsophisticated attacker. For comparison, 263HTTP Basic Authentication (as described in RFC2068) uses BASE64 for a 264similar purpose. CVS uses its own algorithm, described here. 265 266 The scrambled password starts with `A', which serves to identify the 267scrambling algorithm in use. After that follows a single octet for 268each character in the password, according to a fixed encoding. The 269values are shown here, with the encoded values in decimal. Control 270characters, space, and characters outside the invariant ISO 646 271character set are not shown; such characters are not recommended for use 272in passwords. There is a long discussion of character set issues in 273*Note Protocol Notes::. 274 275 0 111 P 125 p 58 276 ! 120 1 52 A 57 Q 55 a 121 q 113 277 " 53 2 75 B 83 R 54 b 117 r 32 278 3 119 C 43 S 66 c 104 s 90 279 4 49 D 46 T 124 d 101 t 44 280 % 109 5 34 E 102 U 126 e 100 u 98 281 & 72 6 82 F 40 V 59 f 69 v 60 282 ' 108 7 81 G 89 W 47 g 73 w 51 283 ( 70 8 95 H 38 X 92 h 99 x 33 284 ) 64 9 65 I 103 Y 71 i 63 y 97 285 * 76 : 112 J 45 Z 115 j 94 z 62 286 + 67 ; 86 K 50 k 93 287 , 116 < 118 L 42 l 39 288 - 74 = 110 M 123 m 37 289 . 68 > 122 N 91 n 61 290 / 87 ? 105 O 35 _ 56 o 48 291 292 293File: cvsclient.info, Node: Protocol, Next: Protocol Notes, Prev: Password scrambling, Up: Top 294 295The CVS client/server protocol 296****************************** 297 298 In the following, `\n' refers to a linefeed and `\t' refers to a 299horizontal tab; "requests" are what the client sends and "responses" 300are what the server sends. In general, the connection is governed by 301the client--the server does not send responses without first receiving 302requests to do so; see *Note Response intro:: for more details of this 303convention. 304 305 It is typical, early in the connection, for the client to transmit a 306`Valid-responses' request, containing all the responses it supports, 307followed by a `valid-requests' request, which elicits from the server a 308`Valid-requests' response containing all the requests it understands. 309In this way, the client and server each find out what the other 310supports before exchanging large amounts of data (such as file 311contents). 312 313* Menu: 314 315 316General protocol conventions: 317 318* Entries Lines:: Transmitting RCS data 319* File Modes:: Read, write, execute, and possibly more... 320* Filenames:: Conventions regarding filenames 321* File transmissions:: How file contents are transmitted 322* Strings:: Strings in various requests and responses 323* Dates:: Times and dates 324 325The protocol itself: 326 327* Request intro:: General conventions relating to requests 328* Requests:: List of requests 329* Response intro:: General conventions relating to responses 330* Response pathnames:: The "pathname" in responses 331* Responses:: List of responses 332* Text tags:: More details about the MT response 333 334An example session, and some further observations: 335 336* Example:: A conversation between client and server 337* Requirements:: Things not to omit from an implementation 338* Obsolete:: Former protocol features 339 340 341File: cvsclient.info, Node: Entries Lines, Next: File Modes, Up: Protocol 342 343Entries Lines 344============= 345 346 Entries lines are transmitted as: 347 348 / NAME / VERSION / CONFLICT / OPTIONS / TAG_OR_DATE 349 350 TAG_OR_DATE is either `T' TAG or `D' DATE or empty. If it is 351followed by a slash, anything after the slash shall be silently ignored. 352 353 VERSION can be empty, or start with `0' or `-', for no user file, 354new user file, or user file to be removed, respectively. 355 356 CONFLICT, if it starts with `+', indicates that the file had 357conflicts in it. The rest of CONFLICT is `=' if the timestamp matches 358the file, or anything else if it doesn't. If CONFLICT does not start 359with a `+', it is silently ignored. 360 361 OPTIONS signifies the keyword expansion options (for example `-ko'). 362In an `Entry' request, this indicates the options that were specified 363with the file from the previous file updating response (*note Response 364intro::., for a list of file updating responses); if the client is 365specifying the `-k' or `-A' option to `update', then it is the server 366which figures out what overrides what. 367 368 369File: cvsclient.info, Node: File Modes, Next: Filenames, Prev: Entries Lines, Up: Protocol 370 371File Modes 372========== 373 374 A mode is any number of repetitions of 375 376 MODE-TYPE = DATA 377 378 separated by `,'. 379 380 MODE-TYPE is an identifier composed of alphanumeric characters. 381Currently specified: `u' for user, `g' for group, `o' for other (see 382below for discussion of whether these have their POSIX meaning or are 383more loose). Unrecognized values of MODE-TYPE are silently ignored. 384 385 DATA consists of any data not containing `,', `\0' or `\n'. For 386`u', `g', and `o' mode types, data consists of alphanumeric characters, 387where `r' means read, `w' means write, `x' means execute, and 388unrecognized letters are silently ignored. 389 390 The two most obvious ways in which the mode matters are: (1) is it 391writeable? This is used by the developer communication features, and 392is implemented even on OS/2 (and could be implemented on DOS), whose 393notion of mode is limited to a readonly bit. (2) is it executable? 394Unix CVS users need CVS to store this setting (for shell scripts and 395the like). The current CVS implementation on unix does a little bit 396more than just maintain these two settings, but it doesn't really have 397a nice general facility to store or version control the mode, even on 398unix, much less across operating systems with diverse protection 399features. So all the ins and outs of what the mode means across 400operating systems haven't really been worked out (e.g. should the VMS 401port use ACLs to get POSIX semantics for groups?). 402 403 404File: cvsclient.info, Node: Filenames, Next: File transmissions, Prev: File Modes, Up: Protocol 405 406Conventions regarding transmission of file names 407================================================ 408 409 In most contexts, `/' is used to separate directory and file names 410in filenames, and any use of other conventions (for example, that the 411user might type on the command line) is converted to that form. The 412only exceptions might be a few cases in which the server provides a 413magic cookie which the client then repeats verbatim, but as the server 414has not yet been ported beyond unix, the two rules provide the same 415answer (and what to do if future server ports are operating on a 416repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been carefully 417thought out). 418 419 Characters outside the invariant ISO 646 character set should be 420avoided in filenames. This restriction may need to be relaxed to allow 421for characters such as `[' and `]' (see above about non-unix servers); 422this has not been carefully considered (and currently implementations 423probably use whatever character sets that the operating systems they 424are running on allow, and/or that users specify). Of course the most 425portable practice is to restrict oneself further, to the POSIX portable 426filename character set as specified in POSIX.1. 427 428 429File: cvsclient.info, Node: File transmissions, Next: Strings, Prev: Filenames, Up: Protocol 430 431File transmissions 432================== 433 434 File contents (noted below as FILE TRANSMISSION) can be sent in one 435of two forms. The simpler form is a number of bytes, followed by a 436linefeed, followed by the specified number of bytes of file contents. 437These are the entire contents of the specified file. Second, if both 438client and server support `gzip-file-contents', a `z' may precede the 439length, and the `file contents' sent are actually compressed with 440`gzip' (RFC1952/1951) compression. The length specified is that of the 441compressed version of the file. 442 443 In neither case are the file content followed by any additional data. 444The transmission of a file will end with a linefeed iff that file (or 445its compressed form) ends with a linefeed. 446 447 The encoding of file contents depends on the value for the `-k' 448option. If the file is binary (as specified by the `-kb' option in the 449appropriate place), then it is just a certain number of octets, and the 450protocol contributes nothing towards determining the encoding (using 451the file name is one widespread, if not universally popular, mechanism). 452If the file is text (not binary), then the file is sent as a series of 453lines, separated by linefeeds. If the keyword expansion is set to 454something other than `-ko', then it is expected that the file conform 455to the RCS expectations regarding keyword expansion--in particular, 456that it is in a character set such as ASCII in which 0x24 is a dollar 457sign (`$'). 458 459 460File: cvsclient.info, Node: Strings, Next: Dates, Prev: File transmissions, Up: Protocol 461 462Strings 463======= 464 465 In various contexts, for example the `Argument' request and the `M' 466response, one transmits what is essentially an arbitrary string. Often 467this will have been supplied by the user (for example, the `-m' option 468to the `ci' request). The protocol has no mechanism to specify the 469character set of such strings; it would be fairly safe to stick to the 470invariant ISO 646 character set but the existing practice is probably 471to just transmit whatever the user specifies, and hope that everyone 472involved agrees which character set is in use, or sticks to a common 473subset. 474 475 476File: cvsclient.info, Node: Dates, Next: Request intro, Prev: Strings, Up: Protocol 477 478Dates 479===== 480 481 The protocol contains times and dates in various places. 482 483 For the `-D' option to the `annotate', `co', `diff', `export', 484`history', `rdiff', `rtag', `tag', and `update' requests, the server 485should support two formats: 486 487 26 May 1997 13:01:40 -0000 ; RFC 822 as modified by RFC 1123 488 5/26/1997 13:01:40 GMT ; traditional 489 490 The former format is preferred; the latter however is sent by the CVS 491command line client (versions 1.5 through at least 1.9). 492 493 For the `-d' option to the `log' request, servers should at least 494support RFC 822/1123 format. Clients are encouraged to use this format 495too (traditionally the command line CVS client has just passed along 496the date format specified by the user, however). 497 498 The `Mod-time' response and `Checkin-time' request use RFC 822/1123 499format (see the descriptions of that response and request for details). 500 501 For `Notify', see the description of that request. 502 503 504File: cvsclient.info, Node: Request intro, Next: Requests, Prev: Dates, Up: Protocol 505 506Request intro 507============= 508 509 By convention, requests which begin with a capital letter do not 510elicit a response from the server, while all others do - save one. The 511exception is `gzip-file-contents'. Unrecognized requests will always 512elicit a response from the server, even if that request begins with a 513capital letter. 514 515 The term "command" means a request which expects a response (except 516`valid-requests'). The general model is that the client transmits a 517great number of requests, but nothing happens until the very end when 518the client transmits a command. Although the intention is that 519transmitting several commands in one connection should be legal, 520existing servers probably have some bugs with some combinations of more 521than one command, and so clients may find it necessary to make several 522connections in some cases. This should be thought of as a workaround 523rather than a desired attribute of the protocol. 524 525