Quick Start

Getting the ram framework

There are several options to install the ram framework on the machine. At the moment the ram framework has been tested on RHEL 6 / CentOS 6 operating systems. The instructions below assume that these operating systems will be used.

Installing from rpm package

  • Get the latest built rpm package from Automake at:

    ...

  • Use yum to install the package, dependencies will be installed automatically:

    # yum install ram-*.noarch.rpm

Installing from source using pip

  • Get the latest version of the of the ram source code from github:

    $ git clone https://github.com/bootforce-dev/ram-framework.git

  • Use pip to install the ram framework to the system:

    $ cd /path/to/ram-framework/src
# pip install .

  • Use standard library from cloned repository:

    # ram paths append /path/to/ram-framework/lib

  • It’s still required to use yum to install ram dependencies:

    # yum install newt-python python-iniparse python-inotify

  • Several units from standard library have additional dependencies. Use yum to install them:

    # yum install libuser-python python-pwquality python-dateutil parted

Getting in touch with ram

Crucial part of the ram framework is the ram command-line utility. It’s interface reuses idea of subcommands known to every user of popular package managers (i.e. apt-get of yum). To get brief hint about basic ram commands just type ram or ram usage:

# ram usage
the ram framework v0.4.4

  To see list of available services:

    $ ram proto

  To see help for a given service:

    $ ram usage <service>

  To see list of all indexed units:

    $ ram index

As shown in the output command ram proto could be used to get list of all available commands (internally called services). Every available command is followed by short command description:

# ram proto
about           . shows description for the unit
apply           * applies configuration to environment
cache           * (deprecated) only for compatibility
debug           * (experimental) use python to import namepath
files           . shows file list managed by the unit
index           . shows list of indexed units
input           * runs dialogs to interact with user
param           . shows parameter list for the unit
print           . shows configuration from storage
probe           * probes service in the environment
purge           * purges configuration from storage
query           * queries configuration from files
reset           * parses configuration from input
setup           * use unit to configure environment
store           * stores configuration to files
proto             shows list of available services
tweak             shows or edits internal parameters
usage             shows usage messages
watch           . watches events sensible for the unit
which           . shows file paths of unit files

To get usage examples for any of the commands just type ram usage <command>:

# ram usage index
index: shows list of indexed units

  To see list of all indexed units:

    $ ram index

  To see list of all units at namepath:

    $ ram index <namepath>

As you can see in the output of ram proto most of ram commands are marked with either * or . mark. Commands without any mark should be considered as generic (i.e. ram proto or ram usage). On the other hand presence of mark indicates that given command operates on units. From the user perspective every unit is a backend to configure particular functionality domain. For example ifconfig unit from standard library provide a way to configure network interfaces and timezone unit serves for timezone selection.

To get the list of all available units just type the ram index command:

# ram index
account                  ---- Account configuration-related functions.
adminwiz                 *..- Create new system user and set password.
datetime                 *... Configure system clock.
diskwiz                  *..- Disk partitioning.
eulawiz                  *--- Find suitable EULA files and ask user to agree on terms.
generic                  ---- Generic functions for units.
hostname                 *... Configure hostname.
ifconfig                 *... Network interface configuration.
internet                 ---- Internet URL manipulation functions for units.
logview                  *--- View system logs using less.
network                  ---- Network configuration-related functions for units.
pipecat                  *--- Generic unit to display pipe data transfer progress.
resolver                 *... Configure DNS resolver.
routing                  *... Configure gateway and routes.
timewiz                  *... Generic time configuration.
timezone                 *..- Configure timezone for the machine.

Issuing commands to ram units

There could be a lot of different units available on the system. And the ram framework aims to provide unified interface to interact with these units. As you can see some of the units shown in the output of ram index command has *-mark. Asterisk indicates that given unit provides menu-based configuration interface. To run configuration menu just type:

# ram setup <unit-name>

Once functionality domain has been configured changes has to be applied to running services. To do this:

# ram apply <unit-name>

How to create own unit

To start development of ram units, the following preparation steps should be done:

  • Create top level library directory and it’s path to ram search path list:

    # mkdir -p <top-level>
# echo <top-level> > /etc/ram/<library-name>

  • Set trace mode to see executed commands and their exit codes:

    # # enable trace-mode
# ram tweak trace on

# # disable trace-mode
# ram tweak trace off

  • Set debug mode to see full tracebacks of ram framework exceptions:

    # # enable debug-mode
# ram tweak debug on

# # disable debug-mode
# ram tweak debug off

  • Create blank unit:

    # ram-mkunit <top-level>/<unit-name>

The latter command creates directory for the unit source code and creates empty files for all standard entry points:

about
Text file with unit description, first line will be used in the output of the index command.
query
This script collects configuration data from the service configuration file.
input
This script uses framework’s calls to interact with a user in a wizard way.
store
This script updates configuration data in the service configuration file.
apply
This script restarts services affected by changed configuration file.

As a result, unit will be available as <unit-name> for any ram command, for example:

# ram print <unit-name>

Example unit

Below is the source code for the unit designed to edit arguments system cron daemon is launched with.

about:

Configure cron daemon

query:

#!/usr/bin/python

import ram.unitlib

from ram.formats import env

if __name__ == '__main__':
    config = ram.unitlib.Config()

    with env.cfgopen('/etc/sysconfig/crond', readonly=True) as source:
        config['options'] = source['CRONDARGS']

input:

#!/usr/bin/python

import ram.unitlib
import ram.widgets

if __name__ == '__main__':
    config = ram.unitlib.Config()

    config['options'], = ram.widgets.RunEntry(
        "Cron daemon arguments",
        "",
        [
            ("Arguments", config['options'], None),
        ],
        allowCancel=True,
        supplySaved=True,
    )

store:

#!/usr/bin/python

import ram.unitlib

from ram.formats import env

if __name__ == '__main__':
    config = ram.unitlib.Config()

    with env.cfgopen('/etc/sysconfig/crond', readonly=False) as target:
        target['CRONDARGS'] = config['options']

apply:

#!/bin/sh

. /usr/share/ram/ram.functions

if [ -f "/var/lock/subsys/crond" -a "/var/lock/subsys/crond" -ot "/etc/sysconfig/crond" ]; then
    service crond condrestart
fi