Next: , Previous: Runtime Options, Up: Top


Appendix B Cfengine network protocol specs

Cfengine uses a simple protocol for communicating via a streams-based tcp connection. This section documents the protocol for anyone who might want to create their own clients or server components to interface with cfengine. Several transfers use a standard buffer size of 4096 bytes. The get-file service uses a character based read interface in which the buffer size is not directly relevant; the size of the get-file buffer is dictated by client-side disk blocksizes.

Each new connection to the remote server daemon must begin with a verification or `login' string whereby the client identifies itself to the server. This information is used to verify the connection by using a reverse DNS lookup and then a double-reverse lookup. This is the basis of hostname authentication.

The various services are listed below:

Stat file
            AUTH client-name server-name
            SYNCH long-time-string STAT filename
          
            reply with OK: <stat-reply-string>
     

Get file
             AUTH client-name server-name
             GET filename
          
             reply with <stream>, break on zero chars received
             or BAD: <message>
     

Opendir
Recursive parsing of directory trees poses a technical problem. If cfengine keeps a connection open and send buffers on a need-to-know basis, then the number of daemon connections will mount up and overload the server. If cfengine caches the entire directory on the client side, allowing the server connection to be severed, then the caching could easily fill the memory of the client. The policy chosen is to attempt to cache all names client-side, in spite of the possible memory problem. The reason for this choice is that, even on large filesystems (max size of paritions with 32 bit pointers is 4GB), the sum memory used by every filename is only of the order of a few megabytes, and this is within reasonable modern memory limits. It is assumed that, even 64 bit users will not create filesystems which are much large than this.
              AUTH client-name server-name
              OPENDIR dir-name
          
              reply with <stream>, break on zero chars received
     

In the future it might be useful to stat the file automatically here and cache the value client-side.

Exec
                 AUTH client-name server-name
                 EXEC option-string
                 CLASSES stream terminated with --- (CFD_TERMINATE)
          
                 reply with <stream>, break on zero chars received
     

Checksum verification
                 MD5 filename 16 byte sequence
          
                 reply with CFD_TRUE for no match (copy) or CFD_FALSE for match (no copy)
     

Reply formatting
The format of reply messages, except for stream data, is
          
            OK: message
          
            BAD: message
          
     

A return prefix of `BAD' implies a failure server-side and the client-side wrapper functions return -1 in this case.

The server daemon currently runs single threaded for all requests except GetFile. Since cfd uses heavyweight processes for general applicablity this avoids unnecessary forking and context switching which would download the server. An upper limit on the number of forks which may be performed is set in the config file. This is mananged using the SIGCHLD signal and a pair of arrays in the master processes (This approach is used to avoid shared memory and semaphore usage which is not portable to many older BSD derivative systems).