add shell-recorder check for commands

ElektraInitiative · May 12, 2023 · cc619a7 · cc619a7
1 parent 2c3f3f2
commit cc619a7
Show file tree

Hide file tree

Showing 2 changed files with 80 additions and 105 deletions.
diff --git a/doc/tutorials/dockerd-specification.md b/doc/tutorials/dockerd-specification.md
@@ -33,7 +33,7 @@ Using `kdb` we will configure the specification.
 
 Before we start just an overview of the structure:
 
-- Specification file location: `~/.config/dockerd/dockerd-daemon.ni`
+- Specification file location: `/docker/daemon.json`
 - Parent specification key: `spec:/sw/dockerd/dockerd/#0/current`
 
 ## Specification Types (values)
@@ -43,14 +43,17 @@ See [type plugin](../../src/plugins/type/README.md) for information about all th
 
 ## Mount Setup
 
+We will be mounting an existing example [dockerd-spec](../../examples/spec/dockerd.ini).
+
 ### Step 1: Mount dockerd specification
 
-First you need to mount a specification file, in this case `dockerd-daemon.ni` to the `spec:/` namespace.
+First you need to mount a specification file, in this case `dockerd.ini` to the `spec:/` namespace.
 You can define the path inside the `spec:/` namespace as `/sw/docker/dockerd/#0/current`, refer to
 [the documentation](https://www.libelektra.org/tutorials/integration-of-your-c-application) to find out more about constructing the name.
 
 ```sh
-sudo kdb mount "$PWD/.config/dockerd/dockerd-daemon.ni" spec:/sw/docker/dockerd/#0/current ni
+sudo kdb mount "$PWD/examples/spec/dockerd.ini" spec:/sw/docker/dockerd/#0/current ni
+# RET: 0
 ```
 
 > NOTE: If you encounter any error saying that you have already mounted some specification with the same name you can run
@@ -62,60 +65,79 @@ sudo kdb mount "$PWD/.config/dockerd/dockerd-daemon.ni" spec:/sw/docker/dockerd/
 ### Step 2: Define a mountpoint
 
 Next you can define, that this specification uses a specific mountpoint for a concrete application configuration.
-So you can say the concrete configuration should be written to `dockerd-daemon.ni`.
+So you can say the concrete configuration should be written to `dockerd.ini`.
 
 ```sh
-kdb meta-set spec:/sw/dockerd/dockerd/#0/current mountpoint ~/.config/dockerd/daemon.ni
+kdb meta-set spec:/sw/dockerd/dockerd/#0/current mountpoint /docker/daemon.json
+# RET: 0
 ```
 
-Your `dockerd-daemon.ni` file should now look something like this:
-
-```sh
-cat $(kdb file spec:/sw/docker/dockerd/#0/current)
+Your `dockerd.ini` file should now contain the `mountpoint` metakey:
 
+> NOTE: Excerpt of `cat $(kdb file spec:/sw/docker/dockerd/#0/current)`.
+ 
+```text
 # ;Ni1
 # ; Generated by the ni plugin using Elektra (see libelektra.org).
 
 # =
 
 # []
-#  meta:/mountpoint = ~/.config/dockerd/daemon.ni
+#  meta:/mountpoint = /dockerd/daemon.json
 ```
 
-### Step 3: Do a specification mount
+### Step 3: Define `json` as plugin
+
+Next we will define that our configuration should be written `json`.
+
+We can do this by running:
 
 ```sh
-sudo kdb spec-mount /sw/docker/dockerd/#0/current ni
+kdb meta-set spec:/sw/dockerd/dockerd/#0/current infos/plugin "yajl"
+# RET: 0
 ```
 
-This specification mount makes sure that the paths where the concrete configuration should be (`daemon.ni`)
-are ready to fulfill our specification (`dockerd-daemon.ni`).
+### Step 4: Do a specification mount
+
+```sh
+sudo kdb spec-mount "/sw/docker/dockerd/#0/current" ni
+# RET: 0
+```
+
+This specification mount makes sure that the paths where the concrete configuration should be (`daemon.json`)
+are ready to fulfill our specification (`dockerd.ini`).
 Be aware that different files get mounted for different namespaces.
-You've a specification file (`dockerd-daemon.ni`) for the `spec`-namespace and three files (`daemon.ni`) on different locations
+You've a specification file (`dockerd.ini`) for the `spec`-namespace and three files (`daemon.json`) on different locations
 for the `dir`- `user`- and `system`-namespaces.
 
-You can see the files by providing the namespace as prefix to the `kdb file` command:
+You can see the files by providing the namespace as prefix to the `kdb file` command (each shows a different path):
 
 ```sh
 kdb file system:/sw/docker/dockerd/#0/current
-# $PWD/.config/dockerd/daemon.ni
+# /dockerd/daemon.json
+```
 
+```sh
 kdb file user:/sw/docker/dockerd/#0/current
-# $PWD/$PWD/.config/daemon.ni
+# STDOUT-REGEX: /dockerd/daemon.json
+```
 
+```sh
 kdb file dir:/sw/docker/dockerd/#0/current
-# $PWD/$PWD/.config/daemon.ni
+# STDOUT-REGEX: /dockerd/daemon.json
 ```
 
-> NOTE: The $PWD should equal the PWD where you run `sudo kdb mount "$PWD/.config/dockerd/dockerd-daemon.ni" spec:/sw/docker/dockerd/#0/current ni`.
+> NOTE: The $PWD should equal the PWD where you run `sudo kdb mount "$PWD/examples/spec/dockerd.ini" spec:/sw/docker/dockerd/#0/current ni`.
 
 > **_Note_**: The files only exist, when configuration values are stored there,
 > i.e. they are created on the first `kdb set` and removed with the last `kdb rm`.
 
 For more information about namespaces in Elektra please see [here](https://www.libelektra.org/man-pages/elektra-namespaces),
 a tutorial about the topic is available [here](https://www.libelektra.org/tutorials/namespaces).
 
-## Writing specification for keys
+## Writing specification for keys (manually)
+
+> NOTE: All output we display for `cat $(kdb file spec:/sw/docker/dockerd/#0/current)` is an excerpt of the whole file output. 
 
 In this example for `dockerd` we will be using 3 types of specifications:
 
@@ -142,32 +164,28 @@ In order to get the above specification we will need the following commands:
 
 ```sh
 kdb meta-set spec:/sw/docker/dockerd/#0/current/data/root type "string"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/data/root description "Root directory of persistent Docker state"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/data/root default "/var/lib/docker"
+# RET: 0
 ```
 
 In case no `data/root` key gets configured the value `/var/lib/docker` is used.
 
 Let us verify that the metakeys have been set correctly:
 
+> NOTE: Excerpt of `cat $(kdb file spec:/sw/docker/dockerd/#0/current)`.
+
 ```sh
 cat $(kdb file spec:/sw/docker/dockerd/#0/current)
 
-# ;Ni1
-# ; Generated by the ni plugin using Elektra (see libelektra.org).
-
-# data/root =
-#  =
-
 # [data/root]
 #  meta:/type = string
 #  meta:/description = Root directory of persistent Docker state
 #  meta:/default = /var/lib/docker
-
-# []
-#  meta:/mountpoint = $PWD/.config/dockerd/daemon.ni
 ```
 
 ### Enum specification (for keys were only a set of possible options can be used)
@@ -185,14 +203,19 @@ In order to get the above specification we will need the following commands:
 
 ```sh
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/cgroupns/mode description "Default mode for containers cgroup namespace"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/cgroupns/mode default "private"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/cgroupns/mode check/enum "#1"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/cgroupns/mode check/enum/#0 "host"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/cgroupns/mode check/enum/#1 "private"
+# RET: 0
 ```
 
 With this configuration we have managed to allow two possible values for `default/cgroupns/mode`.
@@ -201,16 +224,11 @@ The default value if we do not set any configuration is `private`.
 
 Let us verify that the metakeys have been set correctly:
 
+> NOTE: Excerpt of `cat $(kdb file spec:/sw/docker/dockerd/#0/current)`.
+
 ```sh
 cat $(kdb file spec:/sw/docker/dockerd/#0/current)
 
-# ;Ni1
-# ; Generated by the ni plugin using Elektra (see libelektra.org).
-
-# default/cgroupns/mode =
-# data/root =
-#  =
-
 # [default/cgroupns/mode]
 #  meta:/check/enum/#0 = host
 #  meta:/check/enum/#1 = private
@@ -222,9 +240,6 @@ cat $(kdb file spec:/sw/docker/dockerd/#0/current)
 #  meta:/type = string
 #  meta:/description = Root directory of persistent Docker state
 #  meta:/default = /var/lib/docker
-
-# []
-#  meta:/mountpoint = /home/tmakar/.config/dockerd/daemon.ni
 ```
 
 ### Wildcard specifications (for keys where a list of possible options can be used)
@@ -243,10 +258,13 @@ In order to get the above specification we will need following commands:
 
 ```sh
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/ulimits/_ type "long"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/ulimits/_ description "Default ulimits for containers"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/ulimits/_ example "64000"
+# RET: 0
 ```
 
 The above specification will allow us to create any name below the `default/ulimits` key.
@@ -255,17 +273,11 @@ The sample value is `64000`.
 
 Let us verify that the metakeys have been set correctly:
 
+> NOTE: Excerpt of `cat $(kdb file spec:/sw/docker/dockerd/#0/current)`.
+
 ```sh
 cat $(kdb file spec:/sw/docker/dockerd/#0/current)
 
-# ;Ni1
-# ; Generated by the ni plugin using Elektra (see libelektra.org).
-
-# default/ulimits/_ =
-# default/cgroupns/mode =
-# data/root =
-#  =
-
 # [default/ulimits/_]
 #  meta:/type = long
 #  meta:/example = 64000
@@ -282,9 +294,6 @@ cat $(kdb file spec:/sw/docker/dockerd/#0/current)
 #  meta:/type = string
 #  meta:/description = Root directory of persistent Docker state
 #  meta:/default = /var/lib/docker
-
-# []
-#  meta:/mountpoint = /home/tmakar/.config/dockerd/daemon.ni
 ```
 
 ### Array specifications (for keys where a list of possible options can be used)
@@ -323,98 +332,64 @@ In order to get the above specification we will need following commands:
 
 ```sh
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools array/min "0"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools description "Default address pools for node specific local networks (list)"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools/#/base type "string"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools/#/base description "Ip address (ipv4) + subnet"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools/#/base example "172.30.0.0/16"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools/#/size type "short"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools/#/size description "Number of ip addresses in this pool with base"
+# RET: 0
 
 kdb meta-set spec:/sw/docker/dockerd/#0/current/default/address/pools/#/size example "24"
+# RET: 0
 ```
 
 The above specification defines that we can create array elements and each can have `base` or `size`.
 
 ## Final specification code
 
 Your specification should be complete now!
-After adding all the keys that are necessary for our application, your specification should look something like this:
+After adding all the keys that are necessary for our application, you can verify that all specification keys are contained by running:
 
 ```ini
 cat $(kdb file spec:/sw/docker/dockerd/#0/current)
-
-# ;Ni1
-# ; Generated by the ni plugin using Elektra (see libelektra.org).
-
-# default/address/pools/#/base =
-# default/ulimits/_ =
-# default/cgroupns/mode =
-# default/address/pools/#/size =
-# data/root =
-# default/address/pools =
-#  =
-
-# [default/address/pools/#/base]
-#  meta:/type = string
-#  meta:/example = 172.30.0.0/16
-#  meta:/description = Ip address (ipv4) + subnet
-
-# [default/ulimits/_]
-#  meta:/type = long
-#  meta:/example = 64000
-#  meta:/description = Default ulimits for containers
-
-# [default/cgroupns/mode]
-#  meta:/check/enum/#0 = host
-#  meta:/check/enum/#1 = private
-#  meta:/description = Default mode for containers cgroup namespace
-#  meta:/default = private
-#  meta:/check/enum = #1
-
-# [default/address/pools/#/size]
-#  meta:/type = short
-#  meta:/example = 24
-#  meta:/description = Number of ip addresses in this pool with base
-
-# [data/root]
-#  meta:/type = string
-#  meta:/description = Root directory of persistent Docker state
-#  meta:/default = /var/lib/docker
-
-# []
-#  meta:/mountpoint = /home/tmakar/.config/dockerd/daemon.ni
-
-# [default/address/pools]
-#  meta:/description = Default address pools for node specific local networks (list)
-#  meta:/array/min = 0
 ```
 
-## Adding full example specification
+> NOTE: We want display the output because it is too long to display (~ 400-500 lines).
+
+## Adding full example specification (with kdb import)
 
 The above tutorial has given a good overview of how to write a specification.
-You might want to add a full example specification for `dockerd`.
+You might want to add a full example specification for `dockerd` using `kdb import`.
 To do so, follow the next steps.
 
 To make sure we don't run into errors we will clean up everything we have done by now.
 
 1. `sudo kdb rm -r spec:/sw/docker/dockerd/#0/current`
 2. `sudo kdb umount spec:/sw/docker/dockerd/#0/current`
-3. `rm -rf $PWD/.config/dockerd` (make sure that you are in the same PWD as when you run the `sudo kdb mount`)
+3. `rm -rf $PWD/dockerd` (make sure that you are in the same PWD as when you run the `sudo kdb mount`)
 
 Now we are going to add an example of [dockerd-full-spec](../../examples/spec/dockerd.ini).
 
 Make sure you are in the root of the cloned `libelektra` repository:
 
-1. `sudo kdb mount "$PWD/.config/dockerd/dockerd-daemon.ni" spec:/sw/docker/dockerd/#0/current ni`
-2. `kdb meta-set spec:/sw/dockerd/dockerd/#0/current mountpoint ~/.config/dockerd/daemon.ni`
-3. `sudo kdb spec-mount /sw/docker/dockerd/#0/current`
-4. `sudo kdb import spec:/sw/docker/dockerd/#0/current ni < ./examples/spec/dockerd.ini`
+1. `sudo kdb mount "$PWD/dockerd/dockerd-daemon.ni" spec:/sw/docker/dockerd/#0/current ni`
+2. `kdb meta-set spec:/sw/dockerd/dockerd/#0/current mountpoint /dockerd/daemon.ni`
+3. `kdb meta-set spec:/sw/dockerd/dockerd/#0/current infos/plugin "yajl"`
+4. `sudo kdb spec-mount "/sw/docker/dockerd/#0/current"`
+5. `sudo kdb import spec:/sw/docker/dockerd/#0/current ni < ./examples/spec/dockerd.ini`
 
 To verify that everything was created successfully, run:
 

diff --git a/examples/spec/dockerd.ini b/examples/spec/dockerd.ini
@@ -1,6 +1,6 @@
 []
 meta:/mountpoint = /dockerd/daemon.json
-meta:/plugin = yajl
+meta:/infos/plugins = yajl
 
 [runtimes/_]
 meta:/type = string