cfengine  3.15.4
About: CFEngine is a configuration management system for configuring and maintaining Unix-like computers (using an own high level policy language). Community version.
  Fossies Dox: cfengine-3.15.4.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

protocol.h File Reference
#include <cfnet.h>
#include <sequence.h>
#include <protocol_version.h>
Include dependency graph for protocol.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

SeqProtocolOpenDir (AgentConnection *conn, const char *path)
 
bool ProtocolGet (AgentConnection *conn, const char *remote_path, const char *local_path, const uint32_t file_size, int perms)
 
bool ProtocolStatGet (AgentConnection *conn, const char *remote_path, const char *local_path, int perms)
 
bool ProtocolStat (AgentConnection *conn, const char *remote_path, struct stat *stat_buf)
 

Function Documentation

◆ ProtocolGet()

bool ProtocolGet ( AgentConnection conn,
const char *  remote_path,
const char *  local_path,
const uint32_t  file_size,
int  perms 
)

Receives a file from a remote host.

The server will use "/var/cfengine" as working directory if absolute path is not specified. The client will send a request that looks like this: GET <buf_size> <remote_path>

buf_size is the local buffer size: how much of the file to receive in each transaction. It should be aligned to block size (which is usually 4096), but currently the protocol only allows exactly 4095 bytes per transaction.

The function shall fail if connection is not established, or if the server gives a bad response (denoted by a message preceded by "BAD").

Parameters
[in]connThe connection to use
[in]remote_pathPath on remote host
[in]local_pathPath of received file
[in]file_sizeSize of file to get
[in]permsPermissions of local file
Returns
True if file was successfully transferred, false otherwise

Example (for printing each directory entry):

AgentConnection *conn = ServerConnection("127.0.0.1", "666", ...);
bool got_file = ProtocolGet(conn, "masterfiles/update.cf",
"update.cf", CF_MSGSIZE, 0644);
if (got_file)
{
struct stat sb;
stat("update.cf", &sb);
printf("This file is %ld big!\n", sb.st_size);
}
#define CF_MSGSIZE
Definition: cfnet.h:52
AgentConnection * ServerConnection(const char *server, const char *port, unsigned int connect_timeout, ConnectionFlags flags, int *err)
Definition: client_code.c:190
bool ProtocolGet(AgentConnection *conn, const char *remote_path, const char *local_path, const uint32_t file_size, int perms)
Definition: protocol.c:93

In the protocol, this will look like this on the server side: Received: GET masterfiles/update.cf Translated to: GET /var/cfengine/masterfiles/update.cf

Definition at line 93 of file protocol.c.

References BadProtoReply(), CF_CHANGEDSTR1, CF_CHANGEDSTR2, CF_DONE, CF_MSGSIZE, CF_PERMS_DEFAULT, AgentConnection::conn_info, GetErrorStr(), Log(), LOG_LEVEL_ERR, LOG_LEVEL_WARNING, NULL, safe_fopen_create_perms(), SendTransaction(), ConnectionInfo::ssl, StringEqualN(), AgentConnection::this_server, and TLSRecv().

Referenced by ProtocolStatGet().

◆ ProtocolOpenDir()

Seq* ProtocolOpenDir ( AgentConnection conn,
const char *  path 
)

Receives a directory listing from a remote host.

The server will use "/var/cfengine" as working directory if absolute path is not specified. The server sends the directory entries as a string separated by NUL-bytes, and ending with the magic string CFD_TERMINATOR.

The function shall fail if connection is not established, or if the server gives a bad response (denoted by a message preceded by "BAD").

Parameters
[in]connThe connection to use
[in]pathPath on remote host
Returns
A sequence of filenames in the requested directory on success, NULL on failure.

Example (for printing each directory entry):

AgentConnection *conn = ServerConnection("127.0.0.1", "666", ...);
Seq *dir = ProtocolOpenDir(conn, "masterfiles");
for (int i = 0; i < SeqLength(dir); i++)
{
char *entry = SeqAt(i);
printf("%s\n", entry);
}
Seq * ProtocolOpenDir(AgentConnection *conn, const char *path)
Definition: protocol.c:35
size_t SeqLength(const Seq *seq)
Length of the sequence.
Definition: sequence.c:354
static void * SeqAt(const Seq *seq, int i)
Definition: sequence.h:57
Sequence data-structure.
Definition: sequence.h:50

In the protocol, this will look like this on the server side: Received: OPENDIR masterfiles Translated to: OPENDIR /var/cfengine/masterfiles Sends string: ".\0..\0cfe_internal\0cf_promises_release_id\0... ...templates\0update.cf\0" CFD_TERMINATOR

Definition at line 35 of file protocol.c.

References BadProtoReply(), CF_DONE, CF_MSGSIZE, CFD_TERMINATOR, AgentConnection::conn_info, free(), Log(), LOG_LEVEL_ERR, NULL, ReceiveTransaction(), SendTransaction(), SeqAppend(), SeqDestroy(), SeqNew(), StringEqualN(), and xstrdup().

Referenced by CFNetOpenDir().

◆ ProtocolStat()

bool ProtocolStat ( AgentConnection conn,
const char *  remote_path,
struct stat *  stat_buf 
)

Receives statistics about a remote file.

This is a cacheless version of cf_remote_stat from stat_cache.c. This only supports sending with the latest cfnet protocol.

When the STAT request is sent, it is sent together with the current time since the Epoch given by the time syscall denoted by SYNCH <tloc>. If the server is set to deny bad clocks (which is default), it will reject STAT requests from hosts where the clocks differ too much.

When the server accepts the STAT request, it will send each field of the Stat struct from stat_cache.h as numbers delimited by spaces in a single string. Since the Stat struct is not cached, its fields are transferred to the stat_buf parameter.

Example

AgentConnection *conn = ServerConnection("127.0.0.1", "666", ...);
struct stat stat_buf;
ProtocolStat(conn, "masterfiles/update.cf", &stat_buf);
assert((stat_buf.st_mode & S_IFMT) == S_IFREG);
#define S_IFREG
Definition: platform.h:900
#define S_IFMT
Definition: platform.h:909
bool ProtocolStat(AgentConnection *const conn, const char *const remote_path, struct stat *const stat_buf)
Definition: protocol.c:212

This is how the above example looks on the server side: Received: SYNCH 12356789 STAT masterfiles/update.cf Translated to: STAT /var/cfengine/masterfiles/update.cf Sends string: "OK: 0 33188 0 ..." etc.

Parameters
[in]connThe connection to use
[in]remote_pathPath on remote host
[out]stat_bufWhere to store statistics
Returns
true on success, false on failure.

Definition at line 212 of file protocol.c.

References BadProtoReply(), CF_BUFSIZE, CF_DONE, cf_stat(), AgentConnection::conn_info, FileTypeToMode(), GetErrorStr(), Log(), LOG_LEVEL_VERBOSE, LOG_LEVEL_WARNING, NULL, OKProtoReply(), ReceiveTransaction(), SendTransaction(), StatParseResponse(), and AgentConnection::this_server.

Referenced by CFNetStat(), and ProtocolStatGet().

◆ ProtocolStatGet()

bool ProtocolStatGet ( AgentConnection conn,
const char *  remote_path,
const char *  local_path,
int  perms 
)

Receives a file from a remote host, see documentation for ProtocolGet

This funtion will first stat the remote path before attempting to receive it.

Definition at line 193 of file protocol.c.

References Log(), LOG_LEVEL_ERR, NULL, ProtocolGet(), ProtocolStat(), and AgentConnection::this_server.

Referenced by CFNetGetFile().