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).

Go to the first, previous, next, last section, table of contents.