Config yaml file good practices

The purpose of this part is to give advices to write a config yaml file to configure your nodes within the hierarchical view.

There are 4 parts in node config, and default yaml templates can be seen here: Configuration chapter.

Note that a node is totally manageable through the yaml config files and so directly represents the dynamic node behavior.

• Config yaml file good practices
  • Redconf tool
  • Config special variables
    • Example
      • First case from the parent point of view
      • Second case from the child point of view
  • Headers part
  • Config part
    • Namespaces
    • Capabilities
    • Cgroups
  • Export part
    • Export modes
    • Export hierarchical constraints
  • Environ part
    • Environ hierarchical constraints

Redconf tool

redconf tool is a tool that will parse and provide information about a node yaml config file.

The 2 modes can be useful to fix grammar issues with redconf config or to see what overloaded or getting the cumulated/merged config of a node with redconf mergeconfig.

See link_name section for more information about redconf.

Config special variables

There are some particular variables used by redpak that defined proper redpak features.

• LEAF_ALIAS : the leaf/current node alias (e.g. child1)
• LEAF_PATH: the leaf/current node path (/var/redpak/parent/child1)
• NODE_ALIAS: this is the alias of the node: matching node alias from config file (e.g. /var/redpak)
• NODE_PATH: this is the path of the node: matching node path from config file (e.g. /var/redpak)

There are defined in config file as environment variables.

Example

Here an example of nodes with a parent(/var/redpak/parent) and a child(var/redpak/parent/child).

A part of the yaml config parent node:

# parent config yaml file
exports:
  - mount: /home/$LEAF_ALIAS/dir1
    path: $NODE_PATH/dir1
    mode: Restricted
  - mount: /nodes/$NODE_ALIAS/usr
    path: $NODE_PATH/usr
    mode: Restricted

# child config yaml file
exports:
  - mount: /home/$LEAF_ALIAS/dir2
    path: $NODE_PATH/dir2
    mode: Restricted
  - mount: /nodes/$NODE_ALIAS/usr
    path: $NODE_PATH/usr
    mode: Restricted

First case from the parent point of view

Have a look at the expanded variable:

Have a look at expanded result of the parent config file:

redconf mergeconfig -r /var/redpak/parent

# common variables:
# LEAF_ALIAS=parent LEAF_PATH=/var/redpak/parent

# config from parent:
#       NODE_ALIAS=parent
#       NODE_PATH=/var/redpak/parent
- mount: /home/parent/dir1               # /home/$LEAF_ALIAS/dir1
  path: /var/redpak/parent/dir1         # $NODE_PATH/dir1
  mode: Restricted
- mount: /nodes/parent/usr              # /nodes/$NODE_ALIAS/usr
  path: /var/redpak/parent/usr          # $NODE_PATH/usr
  mode: Restricted

Second case from the child point of view

Have a look at the expanded variable:

Have a look at expanded result of the parent config file:

redconf mergeconfig -r /var/redpak/parent/child

# common variables:
# LEAF_ALIAS=child LEAF_PATH=/var/redpak/parent/child

# config from parent:
#       NODE_ALIAS=parent
#       NODE_PATH=/var/redpak/parent
- mount: /home/child/dir1               # /home/$LEAF_ALIAS/dir1
  path: /var/redpak/parent/dir1         # $NODE_PATH/dir1
  mode: Restricted
- mount: /nodes/parent/usr              # /nodes/$NODE_ALIAS/usr
  path: /var/redpak/parent/usr          # $NODE_PATH/usr
  mode: Restricted

# config from child:
#       NODE_ALIAS=child
#       NODE_PATH=/var/redpak/parent/child
- mount: /home/child/dir2               # /home/$LEAF_ALIAS/dir2
  path: /var/redpak/parent/child/dir2   # $NODE_PATH/dir2
  mode: Restricted
- mount: /nodes/child/usr               # /nodes/$NODE_ALIAS/usr
  path: /var/redpak/parent/child/usr    # $NODE_PATH/usr
  mode: Restricted

Headers part

The headers are automatically provided at the node creation, it mainly gives information about the node.

You can see example in default yaml file.

Config part

The config part defined constraints and mandatory values of the nodes.

Some values are cumulated as the path of ldpath other are overloaded by children, typically some proper value of a node as hostname.

Eventually, some values cannot be overloaded, they defined security constraints as namespace values.

Here, the different constraint behavior is explained within the node hierarchy.

• namespaces
• capabilities
• cgroups

Namespaces

redpak handles all linux namespaces, see man documentation: https://man7.org/linux/man-pages/man7/namespaces.7.html

• share_user
• share_cgroup
• share_net
• share_pid
• share_ipc
• share_time

There are 3 states for these values:

• disabled : means that a new namespace is created and none of the children can share it
• enabled : means that the namespace is shared and children are allowed to disable it
• unset : means that the disabled/enabled is authorize in children (default is disabled: meaning that if all nodes in the family is unset the namespace is disabled)

Capabilities

Capabilities can be dropped or add in redpak.

capabilities:
- cap: cap_net_raw
  add: 1 # add capability
- cap: cap_dac_override
  add: 0 # drop capability

If a capability is dropped by a parent, a child cannot add it.

If a capability is added by a parent, a child can drop it.

Cgroups

link to troubleshooting

Cgroup for redpak only works in v2 version. All of the elements of redpak config file respects kernel definitions, please have a look at https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html.

Cgroups already have a hierarchical behavior and so, for now there are no static ways to detect errors with cgroups.

But of course, children cannot bypass parent constraints in cgroups.

For example, if a parent set a max pid to 20 and a child to 50: the max pid in will be 20.

Export part

The export part defines the mount points inside your node, it also inherits from parent export part configuration.

In main cases, a export is defined by a yaml map of 3 elements like below:

- mount: /destination/mount/path/inside/node # the path inside the node
  path: /path/source/to/mount/inside/node # the path source in the system
  mode: Public # the mode

• modes
• hierarchical constraints

Export modes

Below the list of the different export modes in config file and with the hierarchical view:

Export hierarchical constraints

The hierarchical constraints for exports are quite simple. All redundant mounts are ignored by redpak. That is to say, a child cannot mount anything at the same destination.

Thus, a child should never have a same destination mount path in its configuration. redconf mergeconfig can help to check such information. See link_name for more detail.

Example:

# parent configuration
- mode: Restricted
  mount: /var/lib/rpm
  path: /var/parent/rpm

# child configuration
- mode: Public
  mount: /var/lib/rpm
  path: /var/parent/child/rpm

In this case, /var/lib/rpm will be mounted from the parent configuration with Restricted from /var/parent/rpm.

See redconf mergeconfig warning:

redconf mergeconfig --redpath /var/parent/child

- mode: Public
  mount: /var/lib/rpm
  path: /var/parent/child/rpm
  info: /var/parent/parent/child
  warn: key=/var/lib/rpm is overload by /var/parent

Environ part

The environ part defines environment variables inside node.

environ:
  - key: PS1
    value: Rednode($LEAF_ALIAS)>
    mode: Default

Here below the different modes:

• Default: expand $VAR at runtime
• Static: use value without expanding variables
• Execfd: User bash command STDOUT as var value
• Remove: Skim existing environment

Environ hierarchical constraints

The constraints are similar to export constraints, a environment variable cannot be overload by a child.

#  parent
environ:
  - key: MYKEY
    value: THISISMYKEYFROMPARENT
    mode: Default

#  parent
environ:
  - key: MYKEY
    value: THISISMYKEYFROMCHILD
    mode: Default

In this case, MYKEY will be set from the parent configuration with THISISMYKEYFROMCHILD.

See redconf mergeconfig warning:

redconf mergeconfig --redpath /var/parent/child

- mode: Default
  key: MYKEY
  value: THISISMYKEYFROMCHILD
  info: /var/redpak/parent/child
  warn: key=MYKEY is overload by /var/redpak/parent/child