Context

group context

Context, commits and high level network model management.

LSDN context is a core object that manages the network model. It allows the app to keep track of constraints (such as unique names, no two virts using the same interface, etc.), validate the model and commit it to kernel tables.

Context also keeps track of all the child objects (settings, networks, virts, physes, names, etc.) and automatically frees them when it is deleted through lsdn_context_free or lsdn_context_cleanup.

In practically every conceivable case, a single app should only have one context; in fact, only one context should exist per physical host. The library allows you to have multiple contexts at the same time (which is equivalent to having multiple instances of an app), but in such case, the user is responsible for conflicting rules on interfaces. In other words: don’t do this, things will probably crash and burn if you do.

Typedefs

typedef void(*lsdn_nomem_cb)(void *user)

Signature for out-of-memory callback.

Functions

struct lsdn_context* lsdn_context_new(const char * name)

Create new LSDN context.

Initialize a lsdn_context struct and set its name to name. The returned struct must be freed by lsdn_context_free or lsdn_context_cleanup after use.

Return
NULL if allocation failed, pointer to new lsdn_context otherwise.
Parameters
  • name: Context name.

void lsdn_context_set_nomem_callback(struct lsdn_context * ctx, lsdn_nomem_cb cb, void * user)

Configure out-of-memory callback.

By default, LSDN will return an error code to indicate that an allocation failed. This function allows you to set a callback that gets called to handle this condition instead.

Parameters
  • ctx: LSDN context.
  • cb: Callback function.
  • user: User data for the callback function.

void lsdn_context_abort_on_nomem(struct lsdn_context * ctx)

Configure the context to abort on out-of-memory.

This sets the out-of-memory callback to a predefined function that prints an error to stderr and aborts the program.

It is recommended to use this, unless you have a specific way to handle out-of-memory conditions.

See
lsdn_abort_cb
Parameters
  • ctx: LSDN context.

void lsdn_context_free(struct lsdn_context * ctx)

Free a LSDN context.

Deletes the context and all its child objects from memory. Does not delete TC rules from kernel tables.

Use this before exiting your program.

Parameters
  • ctx: Context to free.

void lsdn_context_cleanup(struct lsdn_context * ctx, lsdn_problem_cb cb, void * user)

Clear a LSDN context.

Deletes the context and all its child objects from memory. Also deletes configured TC rules from kernel tables.

Use this to deinitialize the LSDN context and tear down the virtual network.

Parameters
  • ctx: Context to cleanup.
  • cb: Problem callback for encountered errors.
  • user: User data for the problem callback.

void lsdn_context_set_overwrite(struct lsdn_context * ctx, bool overwrite)

Configure rule overwriting.

By default, LSDN will overwrite existing tc rules and network interfaces. This is to ensure that rules created by previous crashed instances do not cause problems. Set this flag to false to prevent overwriting existing rules.

Parameters
  • ctx: LSDN context.
  • overwrite: true if LSDN should overwrite existing kernel objects. false if it should fail if the kernel object already exists.

bool lsdn_context_get_overwrite(struct lsdn_context * ctx)

Query if LSDN should overwrite any of the interfaces or rules.

Return
value of overwrite flag.
See
lsdn_context_set_overwrite

lsdn_err_t lsdn_validate(struct lsdn_context * ctx, lsdn_problem_cb cb, void * user)

Validate network model.

Walks the currently configured in-memory network model and checks for problems. If problems are found, an error code is returned. Problem callback is also invoked for every problem encountered.

Parameters
  • ctx: LSDN context.
  • cb: Problem callback.
  • user: User data for the problem callback.
Return Value

lsdn_err_t lsdn_commit(struct lsdn_context * ctx, lsdn_problem_cb cb, void * user)

Commit network model to kernel tables.

Calculates tc rules based on the current network model, and its difference from the previously committed network model, and applies the changes. After returning successfully, the current network model is in effect.

Performs a model validation (equivalent to calling lsdn_validate) and returns an error if it fails. Afterwards, works through the memory model in two phases:

  • In decommit phase, rules belonging to modified (or deleted) objects are removed from kernel tables. Deleted objects are also freed from memory.
  • In recommit phase, new rules are installed that correspond to new objects or new properties of objects that were removed in the previous phase.

If an error occurs in the recommit phase, a limited rollback is performed and the kernel rules remain in mixed state. Some objects may have been successfully committed, others might still be in the old state because the commit failed. In such case, LSDNE_COMMIT is returned and the user can retry the commit, to install the remaining objects.

If an error occurs in the decommit phase, however, there is no safe way to recover. Given that kernel rules are not installed atomically and there are usually several rules tied to an object, LSDN can’t know what is the installed state after rule removal fails. In this case, LSDNE_INCONSISTENT is returned and the model is considered to be in an inconsistent state. The only way to proceed is to tear down the whole model and reconstruct it from scratch.

Parameters
  • ctx: LSDN context.
  • cb: Problem callback.
  • user: User data for the problem callback.
Return Value
  • LSDNE_OK: Commit was successful. New network model is now active in kernel.
  • LSDNE_VALIDATE: Model validation found problems. Old network model remains active in kernel.
  • LSDNE_COMMIT: Errors were encountered during commit. Kernel is in mixed state, it is possible to retry.
  • LSDNE_INCONSISTENT: Errors were encountered when decommitting rules. Model state is inconsistent with kernel state. You have to start over.

struct lsdn_context
#include <lsdn.h>

LSDN Context.

The base object of the LSDN network model. There should be exactly one instance in your program.

See Context.