firmwared

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 9)

System daemon for running firmwares in containers

firmwared Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# firmwared

## Overview

Daemon responsible of spawning drone firmware instances in containers.  
This document is in markdown format and is best read with a markdown viewer. In
command line, one can use `pandoc README.md | lynx -stdin`.

## Quick start

Instructions start from the root of a sphinx workspace. First unzip the example
firmware.

$ tar xf packages/firmwared/examples/example_firmware.ext2.tar.bz2

Move it to the firmware repository path, *firmwared* is configured to use:

$ mv example_firmware.ext2 firmwares/example_firmware.ext2.firmware

Start firmwared :

# ULOG_LEVEL=D ULOG_STDERR=y ULOG_STDERR_COLOR=y firmwared packages/firmwared/examples/firmwared.conf

Use the example startup script :

# ./packages/firmwared/examples/launch_instance.sh

An xterm should popup, with a console opened on the running instance's console.

## Protocol

### Vocabulary

*Commands* are sent by clients.  The server sends *answers*, which can be
in reaction to a client *command* but not only.  
An *identifier* is either the sha1 of the entity or it's friendly random name.
As the time of writing, there is 2 types of entities, "instances", "firmwares",
entities types are named *folders*.

### Commands

* *ADD\_PROPERTY* FOLDER NAME  
  adds a custom property to the folder FOLDER. If name ends with [], the
  property will be an array. Custom properties are all mutable.
* *COMMANDS*  
  asks the server to list the currently registered commands
* *CONFIG_KEYS*  
  lists all the available configuration keys.
* *DROP* FOLDER IDENTIFIER  
  removes an entity from a folder  
  if the entity is an instance, it must be in the *READY* state. It's pid 1 will
  be killed and it's run artifacts will be removed if
  FIRMWARED\_PREVENT\_REMOVAL isn't set to "y"
* *FOLDERS*  
  asks the server to list the currently registered folders
* *GET\_CONFIG* CONFIG_KEY  
  retrieves the value of the CONFIG_KEY configuration key.
* *GET\_PROPERTY* FOLDER ENTITY\_IDENTIFIER PROPERTY\_NAME  
  retrieves the value of the property PROPERTY for the entity whose name or sha1
  is ENTITY\_IDENTIFIER from the folder FOLDER.
* *HELP* COMMAND  
  sends back a little help on the command COMMAND
* *KILL* INSTANCE\_IDENTIFIER  
  kills an instance, all the processes are killed, the instance is still
  registered and it's rw overlayfs layer is still present  
  the instance must be in the *STARTED* state.  
  the instance switches to the *STOPPING* state, before switching back to the
  *READY* state
* *LIST* FOLDER  
  lists all the items in the folder FOLDER  
  FOLDER is one of folders listed in an answer to a *FOLDERS* command
* *PING*  
  asks for the server to answer with a *PONG* notification
* *PREPARE* FOLDER IDENTIFICATION\_STRING  
  prepares either a firmware or an instance.  
  If FOLDER is equal to "firmwares", then a firmware will be prepared.
  In this case, IDENTIFICATION\_STRING can be either:
   1. a path to an ext2 file system image:  
     in this case, the file will be copied in the firmware repository, indexed
     by firmwared and listed as a usable firmware
   1. an URL:  
     in this case, the file corresponding to the URL will be downloaded locally
     in the firmware repository, indexed by firmwared and listed as a usable
     firmware.
   1. a path to a directory:
     in this case, the path will be considered to correspond to a final
     directory and will be indexed by firmwared and listed as a usable
     firmware.  
  If FOLDER is equal to "instances", then an instance will be created for the 
  firmware of identifier IDENTIFICATION\_STRING, in the *READY* state  
  IDENTIFICATION\_STRING must correspond to an identifier of a registered
  firmware.
* *PROPERTIES* FOLDER  
  asks the server to list the currently registered properties for the folder
  FOLDER
* *QUIT*  
  asks firmwared to exit
* *REMOUNT* INSTANCE\_IDENTIFIER  
  asks to remount the union file system of an instance, to take into account
  modifications in the lower dir (e.g. rebuild of a final dir)
* *SET\_PROPERTY* FOLDER ENTITY\_IDENTIFIER PROPERTY\_NAME PROPERTY\_VALUE  
  sets the value of the property PROPERTY to the value PROPERTY\_VALUE, for the
  entity whose name or sha1 is ENTITY\_IDENTIFIER from the folder FOLDER.
* *SHOW* FOLDER IDENTIFIER  
  asks for all the information on a given entity of a folder
* *START* INSTANCE\_IDENTIFIER  
  launches an instance, which switches to the *STARTED* state and must be in the
  READY state
* *VERSION*  
  sends back informations concerning this firmwared program's version

### Answers

*Answers* are of two types: *acks*, unicast answer to the client which issued a
command and *notifications*, broadcast to all the clients currently listening.

#### Acks

* *PROPERTY\_ADDED* FOLDER PROPERTY  
  answer to an *ADD\_PROPERTY* command  
* *COMMANDS* LIST  
  answer to a *COMMANDS* command, LIST is a space-separated list of the commands
  implemented in firmwared  
* *CONFIG\_KEYS* CONFIG\_KEYS\_LIST  
  answer to a *CONFIG\_KEYS* command, CONFIG\_KEYS\_LIST is a space-separated
  list of the configuration keys available in firmwared
* *ERROR* ERRNO MESSAGE  
  answer to any command whose execution encountered a problem
* *FOLDERS* FOLDERS\_LIST  
  answer to a *FOLDERS* command, FOLDERS\_LIST is a space-separated list of the
  folders registered so far
* *GET\_CONFIG* CONFIG\_KEY CONFIG\_VALUE  
  answer to a *GET\_CONFIG* command
* *GET\_PROPERTY* FOLDER ENTITY\_IDENTIFIER PROPERTY\_NAME PROPERTY\_VALUE  
  answer to a *GET\_PROPERTY* command
* *HELP* COMMAND HELP\_TEXT  
  answer to a *HELP* command
* *LIST* FOLDER COUNT [list of (ID, NAME) pairs]  
  answer to a *LIST* command
* *PONG*  
  answer to a *PING*
* *SHOW* FOLDER ID NAME INFORMATION\_STRING  
  answer to a *SHOW* command. The actual content of the INFORMATION\_STRING is
  dependent on the FOLDER queried and is for display purpose
* *VERSION* VERSION\_DESCRIPTION  
  answer to a *VERSION* command.
* *PROPERTIES* FOLDER PROPERTIES\_LIST  
  answer to a *PROPERTIES* command, PROPERTIES\_LIST is a space-separated list
  of the properties registered for the folder
* *PROPERTY\_SET* FOLDER ENTITY\_IDENTIFIER PROPERTY\_NAME PROPERTY\_VALUE  
  answer to a *SET\_PROPERTY* command
* *REMOUNTED* INSTANCE\_IDENTIFIER  
  answer to a *REMOUNT* command

#### Notifications

* *BYEBYE*  
  notification in reaction to the reception of a *QUIT* command
* *DEAD* INSTANCE\_ID INSTANCE\_NAME  
  notification in reaction to the end of an instance's main process, be it
  caused by a *KILL* command or by "natural death"
* *DROPPED* FOLDER ENTITY\_ID ENTITY\_NAME  
  notification in reaction to a *DROP* command
* *PREPARED* FOLDER ENTITY\_ID ENTITY\_NAME  
  notification in reaction to a *PREPARE* command
* *PREPARE\_PROGRESS* FOLDER IDENTIFICATION\_STRING PROGRESS  
  notification in reaction to a *PREPARE* command, indicating the progression of
  the preparation. PROGRESS is a percentage.
* *STARTED* INSTANCE\_ID INSTANCE\_NAME  
  notification in reaction to a *START* command

### Instance states

* *READY*
  an instance of a firmware has been created and is ready to be started  
  this state is reach after a *PREPARE* command on a firmware, or after a *KILL*
  command, issued on a *STARTED* instance
* *STARTED*  
  the instance is currently running, that is, it's pid 1 is alive  
  this state is reached after a *START* command, issued on a STOPPED instance
* *STOPPING*
  transitional state, reached by an instance after a *KILL* command has been
  issued  
  soon after, the firmware should reach the *READY* state

## Implementation details

### Error handling

The general rule of thumb is :

* most of the time, the return value is for error reporting, a negative errno-
 compatible value is returned on error, while 0 indicates success.
 * if a pointer is returned then a NULL return indicates an error iif errno is
 set to non-zero

## Environment variables

Some base configuration parameters can be modified at startup via the following
environment variables (see config.c for more information). All the supported
variables are documented in the *firmwared*(1) manpage.

## Configuration file

firmwared accepts an optional path to a configuration file as it's first
argument. The syntax is that of the lua language, an example is provided in
examples/firmwared.conf. The admitted keys are the same as the FIRMWARED_XXX
environment variables.

firmwared

firmwared Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

firmwared

firmwared Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README