README.md

1. librocker_client

1.1. Usage Example

// Callback function and its arguments, defined by the caller, to be executed inside ROCKER
void *your_args = NULL;
int start_your_APP(void *args){};

// Initialize a blank RockerRequest struct
RockerRequest req = ROCKER_request_new();

// Assign values to the RockerRequest struct
req.app_id = 1000;
req.uid = 1000;
req.gid = 1000;
req.app_pkg_path = "/tmp/your_APP.squashfs";
req.app_exec_dir = "/var/your_APP/execdir";
req.app_data_dir = "/var/your_APP/datadir";
req.app_overlay_dirs = { "/usr", "/var", "/etc", "/home", "/root" };

// Attempt to run APP inside ROCKER
RockerResult res = ROCKER_enter_rocker(&req, start_my_APP, my_args);

if (ROCKER_ERR_success != res.err_no) {
    // Handle error
}

// APP finished running, clean up the environment
kill(res.guard_pid, SIGKILL);

// More robust cleanup
RockerResult res2 = ROCKER_get_guardname(res.guard_pid);
if (ROCKER_ERR_success == res2.err_no && \
        0 == strcmp(res.guard_name, res2.guard.name)) {
    kill(res.guard_pid, SIGKILL);
}

1.2. API Reference (see lib.h)

//! All interfaces return this struct.
//! NOTE: returned as a value, not a pointer.
//-
//@ err_no: self-descriptive error number
//@ guard_pid: PID of rocker's PID-1 process as seen from outside the rocker
//@ guard_pname: name of rocker's PID-1 process; randomly generated, guaranteed unique by the server
//@ app_pid: PID of the process executing the requested action (app)
typedef struct {
    ROCKER_ERR err_no;
    int app_pid;
    int guard_pid;
    char guard_pname[16];
} RockerResult;

//! Data structure exchanged between rocker_client and rocker_server.
//-
//@ app_id: APP uuid
//@ uid: euid of the App process
//@ gid: egid of the App process
//@ app_pkg_path: path to the App source file, e.g. /apps/xx.squashfs
//@ app_exec_dir: execution path of the App, i.e. mount path of app_pkg_path
//@ app_data_dir: top-level storage path for all data written by the App
//@ app_overlay_dirs[16]: top-level directories for which an overlay layer is needed, e.g. /var; max 16
typedef struct {
    int app_id;
    int uid;
    int gid;

    char *app_pkg_path;
    char *app_exec_dir;
    char *app_data_dir;
    char *app_overlay_dirs[16];
} RockerRequest;

//! API to request creation of a new rocker and run the specified function inside it.
//! Returns a RockerResult struct (NOTE: value, not pointer).
//-
//@ req[in]: configuration data needed to create the new rocker
//@ app[in]: function to execute inside the rocker once it is created
//@ app_args[in]: arguments to pass to the app function
RockerResult
ROCKER_enter_rocker(RockerRequest *req, int (*app) (void *), void *app_args)
__attribute__ ((visibility("default")));

//! Get the name of the specified process from '/proc/<PID>/stat'.
//! Before the client sends a signal to the guard process, compare the name
//! against the original returned at rocker creation to confirm the PID has not been reused.
//-
//@ pid[in]: PID of the target process
RockerResult
ROCKER_get_guardname(int pid)
__attribute__ ((visibility("default")));

//! Return a new RockerRequest instance.
RockerRequest
ROCKER_request_new()
__attribute__ ((visibility("default")));

1.3. Error Codes (self-descriptive, see err_no.h)

//! self-descriptive error number
typedef enum {
    ROCKER_ERR_unknown= -1,
#define ROCKER_ERR_unknown                 ROCKER_ERR_unknown
    ROCKER_ERR_success = 0,
#define ROCKER_ERR_success                 ROCKER_ERR_success
    ROCKER_ERR_sys,
#define ROCKER_ERR_sys                     ROCKER_ERR_sys
    ROCKER_ERR_param_invalid,
#define ROCKER_ERR_param_invalid           ROCKER_ERR_param_invalid
    ROCKER_ERR_server_unaddr_invalid,
#define ROCKER_ERR_server_unaddr_invalid   ROCKER_ERR_server_unaddr_invalid
    ROCKER_ERR_gen_local_addr_failed,
#define ROCKER_ERR_gen_local_addr_failed   ROCKER_ERR_gen_local_addr_failed
    ROCKER_ERR_send_req_failed,
#define ROCKER_ERR_send_req_failed         ROCKER_ERR_send_req_failed
    ROCKER_ERR_recv_resp_failed,
#define ROCKER_ERR_recv_resp_failed        ROCKER_ERR_recv_resp_failed
    ROCKER_ERR_build_rocker_failed,
#define ROCKER_ERR_build_rocker_failed     ROCKER_ERR_build_rocker_failed
    ROCKER_ERR_enter_rocker_failed,
#define ROCKER_ERR_enter_rocker_failed     ROCKER_ERR_enter_rocker_failed
    ROCKER_ERR_app_exec_failed,
#define ROCKER_ERR_app_exec_failed         ROCKER_ERR_app_exec_failed
    ROCKER_ERR_get_guardname_failed,
#define ROCKER_ERR_get_guardname_failed    ROCKER_ERR_get_guardname_failed
} ROCKER_ERR;