VCI Shell Helpers
- John Southworth
Introduction
VCI components may also be created in any programming language one wishes as long as one doesn't mind the overhead of a process being created per request. The implementation functions for the component will be invoked by running a new process anytime an action occurs. Any state that needs to be maintained by one of these components must be carefully thought through by the implementation and stored when appropriate. Since the component does not reside in memory we call these "ephemeral" components. Ephemeral components are managed by a daemon called ephemerad. Subscription to notifications in the ephemeral case can be tricky and a separate daemon "notifyd" exists to aid in reaction to notifications by ephemeral components.
These helpers are meant to be used for simple, low throughput components. Use a native VCI component if you are unsure which implementation is best. |
Ephemerad
Ephemerad is the service that will listen on the bus and run the ephemeral scripts. This service is used in conjunction with the existing VCI tools to generate the illusion that all the components are persistent and running on the bus. It does this by acting as a proxy for VCI requests.
Component defintions
To create an ephemeral component one must supply a ".component" file just like any other VCI component. Ephemeral components need to be marked as "Ephemeral=true" in this file so that the VCI helpers create the correct system configuration for an ephemeral component. See the example below.
[Vyatta Component]
Name=net.vyatta.eng.vci.example.ephemeral.toaster
Description=Ephemeral version of the VCI Toaster
Ephemeral=true
ConfigFile=/etc/toaster.conf
[Model net.vyatta.eng.vci.example.ephemeral.toaster.v1]
Modules=toaster
ModelSets=vyatta-v1 |
Instance defintions
Ephemerad needs to know what script to call when performing an action for the component. For this we use an instance definition such as the one below.
[Component]
Name=net.vyatta.eng.vci.example.ephemeral.toaster
Start=/lib/vci-toaster-ephemeral --action=start
Stop=/lib/vci-toaster-ephemeral --action=stop
[Model net.vyatta.eng.vci.example.ephemeral.toaster.v1]
Config/Check=/lib/vci-toaster-ephemeral/vci-toaster --action=validate
Config/Set=/lib/vci-toaster-ephemeral/vci-toaster --action=commit
Config/Get=/lib/vci-toaster-ephemeral/vci-toaster --action=get-config
State/Get=/lib/vci-toaster-ephemeral/vci-toaster --action=get-state
RPC/toaster/make-toast=/lib/vci-toaster-ephemeral/vci-toaster --action=make-toast
RPC/toaster/cancel-toast=/lib/vci-toaster-ephemeral/vci-toaster --action=cancel-toast
RPC/toaster/restock-toaster=/lib/vci-toaster-ephemeral/vci-toaster --action=restock-toaster |
This instance definition tells ephemerad how to call the scripts when bus actions are called. There is one instance definition per managed component. The instance definitions are installed in '/lib/vci/ephemera/instances'.
Calling environment
When ever one of the actions is called the following environment is present. Ephemerad follows typical UNIX environment conventions when calling the actions. Input and output are done via stdin, stdout and stderr. Some metadata is also present to differentiate what action was called via the environment. The called action may return success or failure via the exit code.
UNIX interface | Function |
|---|---|
stdin | rfc7951 encoded data for the function |
stdout | rfc7951 output for the function |
stderr | rfc7951 representation of the error if any |
VCI_COMPONENT_NAME | The name of the component |
VCI_MODEL_NAME | The name of the model |
EPHEMERA_MESSAGE | The statement from the instance file that is being invoked. 'Config/Get', 'RPC/module/name', etc. |
exit code | determines whether the operation was successful (standard interpretation: 0 success, non-0 failure) |
Component activation
Initial component activation looks like the following.
Subsequent calls to an active component will then simply be the second half of the call sequence.
Limitations
If ephemerad is stopped and started again (not restart) then only OnBoot components will listen on the bus.
Restart works as expected due to the PartOf relationship
Happens during install of the ephemerad package
Notifyd
Notifyd is a component that listens for configured notifications on the VCI bus and invokes the script that was configured. This will allow for feature defined scripts to be called when notifications are sent on the VCI bus. Ephemeral notifications can be configured by other scripts using YANG defined RPCs into notifyd. Notifyd will execute an appropriate number of scripts in parallel using a queue of (events,handlers) pairs to ensure that execution order is preserved with regards to causal order of arrival. This does not mean that events are totally ordered but that if an event a caused event b to occur that a will always be processed before b. Order of called scripts for a given notification is arbitrary and not guaranteed to be consistent.
Notifyd stores ephemeral calls in a cache that can be loaded again if the daemon crashes or restarts.
Notifyd supports loading of notification listeners from 2 locations:
Ephemerally requested during operation
System statically added at package install time
Static file definitions
[When module:name]
script=foo --arg1 --arg2 |
Multiple When subsections can be specified per file and multiple scripts per When. Multiple scripts must be ',' separated for now.
Calling environment
When ever one of the actions is called the following environment is present. Notifiy follows typical UNIX environment conventions when calling the actions. Input and output are done via stdin, stdout and stderr. Some metadata is also present to differentiate what action was called via the environment. The called action may return success or failure via the exit code.
UNIX interface | Function |
|---|---|
stdin | rfc7951 encoded data for the notification |
stdout | output of the script. Logged to notifyd's journal as 'DEBUG' |
stderr | error output of the script. Logged to notifyd's journal as 'ERR' |
NOTIFYD_MODULE | YANG module for the notification |
NOTIFYD_NOTIF | YANG notification name |
exit code | determines whether the operation was successful (standard interpretation: 0 success, non-0 failure) |
Limitations
There is a limit to the number of scripts that can be called in parallel and scripts take some time to execute. Notifications may be delayed since there is a FIFO queue of events to the worker. This means that care should be take that notification scripts are used sparingly and are lightweight.
This is being supplied as a general facility to support lightweight features of the system. Features with heavier requirements should implement a full component to react to events.