bibop/COOKBOOK.md at master · essentialkaos/bibop

Recipe Syntax
- Comments
- Data types
- Global keywords
- Variables
- Actions
  - Common
    - exit
    - wait
    - template
  - Input/Output
  - Filesystem
    - chdir
    - mode
    - owner
    - exist
    - link
    - readable
    - writable
    - executable
    - dir
    - empty
    - empty-dir
    - checksum
    - checksum-read
    - file-contains
    - copy
    - move
    - touch
    - mkdir
    - remove
    - chmod
    - chown
    - truncate
    - cleanup
    - backup
    - backup-restore
  - System
    - process-works
    - wait-pid
    - wait-fs
    - wait-connect
    - connect
    - app
    - signal
    - env
    - env-set
  - Users/Groups
  - Services
  - HTTP
  - Libraries
  - Python
    - python2-package
    - python3-package
Examples

Recipe Syntax

Comments

In bibop recipe all comments must have # prefix.

Example:

# Logs directory must be empty before tests
command "-" "Check environment"
  empty-dir /var/log/my-app

Data types

Every action or variable can have values with next types:

String
Number (integer or floating point)
Boolean (true/false or yes/no)
File mode (integer with leading zero)

▲ To avoid splitting strings with whitespaces, value can be wrapped by double quotes:

command "echo 'My message'" "Simple echo command"
  expect "My message"
  exit 0

▲ If value contains double quotes, it must be wrapped by singular quotes:

command "myapp john" "Check user"
  expect 'Unknown user "john"'
  exit 1

Global keywords

`pkg`

One or more required packages for tests.

Syntax: pkg <package-name>…

Arguments:

package-name - Package name (String)

Example:

pkg php nginx libhttp2 libhttp2-devel

`unsafe-actions`

Allows doing unsafe actions (like removing files outside of working directory).

Syntax: unsafe-actions <flag>

Arguments:

flag - Flag (Boolean) [no by default]

Example:

unsafe-actions yes

`require-root`

Requires root privileges for the recipe.

If you use command syntax for executing the command as another user, this requirement will be enabled by automatically.

Syntax: require-root <flag>

Arguments:

flag - Flag (Boolean) [no by default]

Example:

require-root yes

`fast-finish`

If set to Yes, the test will be finished after the first failure.

Syntax: fast-finish <flag>

Arguments:

flag - Flag (Boolean) [no by default]

Example:

fast-finish yes

`lock-workdir`

If set to Yes, the current directory will be changed to working dir for every command.

Syntax: lock-workdir <flag>

Arguments:

flag - Flag (Boolean) [yes by default]

Example:

lock-workdir no

`unbuffer`

Disables I/O stream buffering.

Syntax: unbuffer <flag>

Arguments:

flag - Flag (Boolean) [no by default]

Example:

unbuffer yes

`https-skip-verify`

Disables TLS/SSL certificates verification.

Syntax: https-skip-verify <flag>

Arguments:

flag - Flag (Boolean) [no by default]

Example:

https-skip-verify yes

`delay`

Delay between commands.

Syntax: delay <seconds>

Arguments:

delay - Delay in seconds (Float)

Example:

delay 1.5

`command`

Executes command. If you want to do some actions and checks without executing any binary ("hollow" command), you can use "-" (minus) as a command name.

You can execute the command as another user. For using this feature, you should define user name at the start of the command, e.g. nobody:echo 'ABCD'. This feature requires that bibop utility was executed with super user privileges (e.g. root).

Commands could be combined into groups. By default, every command has its own group. If you want to add a command to the group, use + as a prefix (e.g., +command). See the example below. If any command from the group fails, all the following commands in the group will be skipped.

You can define tag and execute the command with a tag on demand (using -t / --tag option of CLI). By default, all commands with tags are ignored.

Also, there is a special tag — teardown. If a command has this tag, this command will be executed even if fast-finish is set to true.

Syntax: command:tag <cmd-line> [description]

Arguments:

cmd-line - Full command with all arguments
descriprion - Command description [Optional]

Examples:

command "echo 'ABCD'" "Simple echo command"
  expect "ABCD"
  exit 0

command "USER=john ID=123 echo 'ABCD'" "Simple echo command with environment variables"
  expect "ABCD"
  exit 0

command "postgres:echo 'ABCD'" "Simple echo command as postgres user"
  expect "ABCD"
  exit 0

command "-" "Check configuration files (hollow command)"
  exist "/etc/myapp.conf"
  owner "/etc/myapp.conf" "root"
  mode "/etc/myapp.conf" 644

command:init "myapp initdb" "Init database"
  exist "/var/db/myapp.db"

command "-" "Replace configuration file"
  backup {redis_config}
  copy redis.conf {redis_config}

command "systemctl start {service_name}" "Start Redis service"
  wait {delay}
  service-works {service_name}
  connect tcp :6379

+command "systemctl status {service_name}" "Check status of Redis service"
  expect "active (running)"

+command "systemctl restart {service_name}" "Restart Redis service"
  wait {delay}
  service-works {service_name}
  connect tcp :6379

+command "redis-cli CONFIG GET logfile" "Check Redis Client"
  exit 0
  output-contains "/var/log/redis/redis.log"

+command "systemctl stop {service_name}" "Stop Redis service"
  wait {delay}
  !service-works {service_name}
  !connect tcp :6379

command "-" "Configuration file restore"
  backup-restore {redis_config}

Variables

You can define global variables using keyword var and than use them in actions and commands. Variables defined with var keyword is read-only and cannot be set by *-read actions.

Variables can contain other variables defined earlier.

Also, there are some run-time variables:

Name	Description
`ENV:*`	Environment variable (see example below)
`DATE:*`	Current date with given format (see example below)
`WORKDIR`	Path to working directory
`TIMESTAMP`	Unix timestamp
`HOSTNAME`	Hostname
`IP`	Host IP
`OS`	OS name (linux/darwin/freebsd…)
`ARCH`	System architecture (i386/i686/x86_64/arm…)
`ARCH_NAME`	System architecture name (386/686/amd64/arm…)
`ARCH_BITS`	System architecture (32/64)
`LIBDIR`	Path to directory with shared libraries
`LIBDIR_LOCAL`	Path to local directory with shared libraries
`PYTHON2_VERSION`	Python 2.x version
`PYTHON2_SITELIB`	Path to directory where pure Python 2 modules are installed (`/usr/lib/python2.X/site-packages`)
`PYTHON2_SITEARCH`	Path where Python 2 extension modules (e.g. C compiled) are installed (`/usr/local/lib64/python2.X/site-packages`)
`PYTHON3_VERSION`	Python 3.x version
`PYTHON3_SITELIB`	Path to directory where pure Python 3 modules are installed (`/usr/lib/python3.X/site-packages`)
`PYTHON3_SITEARCH`	Path to directory where Python 3 extension modules (e.g. C compiled) are installed (`/usr/lib64/python3.X/site-packages`)
`PYTHON3_BINDING_SUFFIX`	Suffix for Python 3.x bindings
`ERLANG_BIN_DIR`	Path to directory with Erlang executables

You can view and check all recipe variables using -V/--variables option:

bibop my-app.recipe --variables

Examples:

var service      nginx
var service_user nginx
var data_dir     /var/cache/{service}

command "service start {service}" "Starting service"
  service-works {service}
  exist {data_dir}

command "-" "Check shared library"
  exist {LIBDIR}/mylib.so
  mode {LIBDIR}/mylib.so 755

var app_name mysuppaapp

command "go build {app_name}.go" "Build application"
  exist {ENV:GOPATH}/bin/{app_name}_{DATE:%Y%m%d}

Actions

Action do or check something after executing command.

▲ All actions must have prefix (two spaces or horizontal tab) and follow command token.

Common

`exit`

Waits till command will be finished and then checks exit code.

Syntax: exit <code> [max-wait]

Arguments:

code - Exit code (Integer)
timeout - Max wait time in seconds (Float) [Optional | 60 seconds]

Negative form: Yes

Examples:

command "git clone git@github.com:user/repo.git" "Repository clone"
  exit 0

command "git clone git@github.com:user/repo.git" "Repository clone"
  exit 0 60

`wait`

Makes pause before the next action.

Syntax: wait <duration>

Arguments:

duration - Duration in seconds (Float)

Negative form: No

Example:

command "echo 'ABCD'" "Simple echo command"
  wait 3.5

`template`

Creates a file from a template. If file already exists, it will be rewritten with the same UID, GID and mode.

▲ Note that 'template' action will not automatically backup the destination file if it already exists (use backup and backup-restore actions to preserve the original file). Also, the created file will remain after tests execution if it was created outside the working directory.

You can use the following methods in your templates:

Var "name" - get variable value;
Is "name" "value" - compare variable value.

Simple example:

# Sysconfig for postgresql service

PG_ENGINE=""
PG_POSTMASTER=""
{{ if not .Is "data_dir" "" }}
PG_DATA="{{ .Var "data_dir" }}/db"
{{ else }}
PG_DATA=""
{{ end }}
PG_LOG=""
PG_UPLOG=""
PG_SOCKET_DIR=""
TIMEOUT=""
DISABLE_AUTO_NUMA=""

Syntax: template <source> <dest> [file-mode]

Arguments:

source - Path to template file (String)
dest - Destination path (String)
file-mode - Destination file mode (Integer) [Optional | 644]

Negative form: No

Example:

command "-" "Create configuration file"
  template app.template /etc/myapp.conf

command "-" "Create configuration file"
  template app.template /etc/myapp.conf 640

command "-" "Replace configuration file"
  backup /etc/myapp.conf
  template app.template /etc/myapp.conf 640

...

command "-" "Restore original configuration file"
  backup-restore /etc/myapp.conf

Input/Output

Be aware that the output store limited to 2 Mb of data for each stream (stdout and stderr). So if command generates lots of output data, it better to use expect action to working with the output.

Also, expect checks output store every 25 milliseconds. It means that expect action can handle 80 Mb/s output stream without losing data. But if the command generates such an amount of output data it is not the right decision to test it with bibop.

`expect`

Expects some substring in command output.

Syntax: expect <substr> [max-wait]

Arguments:

substr - Substring for search (String)
max-wait - Max wait time in seconds (Float) [Optional | 5 seconds]

Negative form: No

Example:

command "echo 'ABCD'" "Simple echo command"
  expect "ABCD"

command "echo 'ABCD'" "Simple echo command with 1 seconds timeout"
  expect "ABCD" 1

`print`

Prints some data to stdin.

Syntax: print <data>

Arguments:

data - Some text (String)

Negative form: No

Example:

command "echo 'ABCD'" "Simple echo command"
  print "abcd"

`wait-output`

Waits till command prints any data.

Syntax: wait-output <timeout>

Arguments:

timeout - Max wait time in seconds (Float)

Negative form: No

Example:

command "echo 'ABCD'" "Simple echo command"
  wait-output 10.0

`output-match`

Checks output with given regular expression.

Syntax: output-match <regexp>

Arguments:

regexp - Regexp pattern (String)

Negative form: Yes

Example:

command "echo 'ABCD'" "Simple echo command"
  output-match "[A-Z]{4}"

`output-contains`

Checks if the output contains given substring.

Syntax: output-contains <substr>

Arguments:

substr - Substring for search (String)

Negative form: Yes

Example:

command "echo 'ABCD'" "Simple echo command"
  output-contains "BC"

`output-empty`

Checks if the output is empty.

Syntax: output-empty

Negative form: Yes

Example:

command "echo 'ABCD'" "Simple echo command"
  !output-empty

`output-trim`

Trims output (remove output data from store).

Syntax: output-trim

Negative form: No

Example:

command "echo 'ABCD'" "Simple echo command"
  output-trim

Filesystem

`chdir`

Changes current directory to given path.

▲ Be aware that if you don't set lock-workdir to no for every command we will set current directory to working directory defined through CLI option.

Syntax: chdir <path>

Arguments:

path - Path to file or directory (String)

Negative form: No

Example:

command "-" "Check environment"
  chdir /var/log
  exist secure.log

`mode`

Checks file or directory mode bits.

Syntax: mode <path> <mode>

Arguments:

path - Path to file or directory (String)
mode - Mode (Octal)

Negative form: Yes

Example:

command "-" "Check environment"
  mode /home/user/file.log 0644
  mode /home/user 4755

`owner`

Checks file or directory owner.

Syntax: owner <path> <user>:<group>

Arguments:

path - Path to file or directory (String)
user - User name (String)
group - Group name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  owner /home/john/file.log john
  owner /home/john/file1.log :sysadmins
  owner /home/john/file1.log john:sysadmins

`exist`

Checks if file or directory exist.

Syntax: exist <path>

Arguments:

path - Path to file or directory (String)

Negative form: Yes

Example:

command "-" "Check environment"
  exist /home/john/file.log

`link`

Checks if link points on given file or directory. Action follows all links until it finds a non-link object.

Syntax: link <link> <target>

Arguments:

link - Path to link (String)
target - Path to target file or directory (String)

Negative form: Yes

Example:

command "-" "Check environment"
  link /etc/myapp.conf /srv/myapp/common/myapp.conf

`readable`

Checks if file or directory is readable for some user.

Syntax: readable <username> <path>

Arguments:

username - User name (String)
path - Path to file or directory (String)

Negative form: Yes

Example:

command "-" "Check environment"
  readable john /home/john/file.log

`writable`

Checks if file or directory is writable for some user.

Syntax: writable <username> <path>

Arguments:

username - User name (String)
path - Path to file or directory (String)

Negative form: Yes

Example:

command "-" "Check environment"
  writable john /home/john/file.log

`executable`

Checks if file or directory is executable for some user.

Syntax: executable <username> <path>

Arguments:

username - User name (String)
path - Path to file or directory (String)

Negative form: Yes

Example:

command "-" "Check environment"
  executable john /usr/bin/myapp

`dir`

Checks if given target is directory.

Syntax: dir <path>

Arguments:

path - Path to directory (String)

Negative form: Yes

Example:

command "-" "Check environment"
  dir /home/john/abcd

`empty`

Checks if file is empty.

Syntax: empty <path>

Arguments:

path - Path to file (String)

Negative form: Yes

Example:

command "-" "Check if log file is empty"
  empty "/home/john/file.log"

`empty-dir`

Checks if directory is empty.

Syntax: empty-dir <path>

Arguments:

path - Path to directory (String)

Negative form: Yes

Example:

command "-" "Check for empty directory"
  empty-dir /var/log/my-app

`checksum`

Checks file SHA256 checksum.

Syntax: checksum <path> <hash>

Arguments:

path - Path to file (String)
hash - SHA256 checksum (String)

Negative form: Yes

Example:

command "-" "Check configuration checksum"
  checksum /etc/myapp/myapp.conf 88D4266FD4E6338D13B845FCF289579D209C897823B9217DA3E161936F031589

`checksum-read`

Checks file SHA256 checksum and writes it into the variable.

Syntax: checksum-read <path> <variable>

Arguments:

path - Path to file (String)
variable - Variable name (String)

Negative form: No

Example:

command "-" "Get configuration checksum"
  checksum-read /etc/myapp/myapp.conf log_checksum
  checksum /etc/myapp/myapp.conf {log_checksum}

`file-contains`

Checks if file contains some substring.

Syntax: file-contains <path> <substr>

Arguments:

path - Path to file (String)
substr - Substring for search (String)

Negative form: Yes

Example:

command "-" "Check logs for data"
  file-contains /home/john/file.log "ERROR: "

`copy`

Makes copy of file or directory.

Syntax: copy <source> <dest>

Arguments:

source - Path to source file or directory (String)
dest - Path to destination (String)

Negative form: No

Example:

command "-" "Create copy of log file"
  copy /home/john/file.log /home/john/file2.log

`move`

Moves file or directory.

Syntax: move <source> <dest>

Arguments:

source - Path to source file or directory (String)
dest - New destination (String)

Negative form: No

Example:

command "-" "Check environment"
  move /home/john/file.log /home/john/file2.log

`touch`

Changes file timestamps.

Syntax: touch <path>

Arguments:

path - Path to file (String)

Negative form: No

Example:

command "-" "Check environment"
  touch /home/john/file.log

`mkdir`

Creates a directory.

Syntax: mkdir <path>

Arguments:

path - Path to directory (String)

Negative form: No

Example:

command "-" "Check environment"
  mkdir /home/john/abcd

`remove`

Removes file or directory.

▲ Deleting files created due to the test in working dir is not required. bibop automatically deletes all files created due test process.

Syntax: remove <target>

Arguments:

target - Path to file or directory (String)

Negative form: No

Example:

command "-" "Check environment"
  remove /home/john/abcd

`chmod`

Changes file mode bits.

Syntax: chmod <target> <mode>

Arguments:

target - Path to file or directory (String)
mode - Mode (Integer)

Negative form: No

Example:

command "-" "Change mode for directory"
  chmod /home/john/abcd 755
  chmod /home/john/abcd.txt 644

`chown`

Changes file or directory owner.

Syntax: chown <path> <user>:<group>

Arguments:

path - Path to file or directory (String)
user - User name (String)
group - Group name (String)

Negative form: No

Example:

command "-" "Set owner for files"
  chown /home/john/file.log john
  chown /home/john/file1.log :sysadmins
  chown /home/john/file1.log john:sysadmins

`truncate`

Changes the size of the file to zero.

Syntax: truncate <target>

Arguments:

target - Path to file (String)

Negative form: No

Example:

command "-" "Clear log file"
  truncate /var/log/my-app/app.log

`cleanup`

Removes all directories and files in the given directory.

Syntax: cleanup <dir>

Arguments:

dir - Path to directory with data (String)

Negative form: No

Example:

command "-" "Remove app data"
  cleanup /srv/myapp/data
  cleanup /srv/myapp/backups

`backup`

Creates backup for the file.

Syntax: backup <path>

Arguments:

path - Path to file (String)

Negative form: No

Example:

command "-" "Configure environment"
  backup /etc/myapp.conf

`backup-restore`

Restores file from backup. backup-restore can be executed multiple times with different commands.

Syntax: backup-restore <path>

Arguments:

path - Path to file (String)

Negative form: No

Example:

command "-" "Configure environment"
  backup /etc/myapp.conf
  backup-restore /etc/myapp.conf

System

`process-works`

Checks if process is works.

Syntax: process-works <pid-file>

Arguments:

pid-file - Path to PID file (String)

Negative form: Yes

Example:

command "-" "Check environment"
  process-works /var/run/service.pid

`wait-pid`

Waits for PID file.

Syntax: wait-pid <pid-file> [timeout]

Arguments:

pid-file - Path to PID file (String)
timeout - Timeout in seconds (Float) [Optional | 60 seconds]

Negative form: Yes

Examples:

command "-" "Check environment"
  wait-pid /var/run/service.pid

command "-" "Check environment"
  wait-pid /var/run/service.pid 90

`wait-fs`

Waits for file/directory.

Syntax: wait-fs <target> [timeout]

Arguments:

target - Path to file or directory (String)
timeout - Timeout in seconds (Float) [Optional | 60 seconds]

Negative form: Yes

Examples:

command "service myapp start" "Starting MyApp"
  wait-fs /var/log/myapp.log

command "service myapp start" "Starting MyApp"
  wait-fs /var/log/myapp.log 180

`wait-connect`

Waits for connection.

Syntax: wait-connect <network> <address> [timeout]

Arguments:

network - Network name (udp, tcp, ip) (String)
address - Network address (String)
timeout - Timeout in seconds (Float) [Optional | 60 seconds]

Negative form: Yes

Examples:

command "service myapp start" "Starting MyApp server"
  wait-connect tcp :80

command "service myapp start" "Starting MyApp server"
  wait-connect tcp 127.0.0.1:80 15

`connect`

Checks if it possible to connect to some address.

Syntax: connect <network> <address>

Arguments:

network - Network name (udp, tcp, ip) (String)
address - Network address (String)
timeout - Timeout in seconds (Float) [Optional | 1 second]

Negative form: Yes

Example:

command "-" "Check environment"
  connect tcp :6379
  connect tcp 192.0.2.1:http
  connect tcp 192.0.2.1:http 60
  connect udp [fe80::1%lo0]:53

`app`

Checks if application binary is present in PATH.

Syntax: app <name>

Arguments:

name - Application name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  app wget

`signal`

Sends signal to process.

If pid-file not defined signal will be sent to current process.

Syntax: signal <sig> [pid-file]

Arguments:

sig - Signal name or code (String or Number)
pid-file - Path to PID file (String) [Optional]

Negative form: No

Examples:

command "myapp --daemon" "Check my app"
  signal HUP

command "myapp --daemon" "Check my app"
  signal HUP /var/run/myapp.pid

command "myapp --daemon" "Check my app"
  signal 16

`env`

Checks environment variable value.

Syntax: env <name> <value>

Arguments:

name - Environment variable name (String)
value - Environment variable value (String)

Negative form: Yes

Example:

command "-" "Check environment"
  env LANG en_US.UTF-8

`env-set`

Sets environment variable.

Syntax: env-set <name> <value>

Arguments:

name - Environment variable name (String)
value - Environment variable value (String)

Negative form: No

Example:

command "-" "Prepare environment"
  env-set HTTP_PROXY "http://127.0.0.1:3300"

Users/Groups

`user-exist`

Checks if user is exist on system.

Syntax: user-exist <username>

Arguments:

username - User name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  user-exist nginx

`user-id`

Checks if user has some ID (UID).

Syntax: user-id <username> <id>

Arguments:

username - User name (String)
id - UID (Integer)

Negative form: Yes

Example:

command "-" "Check environment"
  user-id nginx 345

`user-gid`

Checks if user has some group ID (GID).

Syntax: user-gid <username> <id>

Arguments:

username - User name (String)
id - GID (Integer)

Negative form: Yes

Example:

command "-" "Check environment"
  user-gid nginx 994

`user-group`

Checks if user is a part of some group.

Syntax: user-group <username> <groupname>

Arguments:

username - User name (String)
groupname - Group name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  user-group nginx nobody

`user-shell`

Checks if user has some shell.

Syntax: user-shell <username> <shell>

Arguments:

username - User name (String)
shell - Shell binary (String)

Negative form: Yes

Example:

command "-" "Check environment"
  user-shell nginx /usr/sbin/nologin

`user-home`

Checks if user has some home directory.

Syntax: user-shell <username> <home-dir>

Arguments:

username - User name (String)
home-dir - Directory (String)

Negative form: Yes

Example:

command "-" "Check environment"
  user-home nginx /usr/share/nginx

`group-exist`

Checks if group is exist on system.

Syntax: group-exist <groupname>

Arguments:

groupname - Group name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  group-exist nginx

`group-id`

Checks if group has some ID (GID).

Syntax: group-id <groupname> <id>

Arguments:

groupname - Group name (String)
id - GID (Integer)

Negative form: Yes

Example:

command "-" "Check environment"
  group-id nginx 994

Services

`service-present`

Checks if service is present on the system.

Syntax: service-present <service-name>

Arguments:

service-name - Service name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  service-present nginx

`service-enabled`

Checks if auto start is enabled for service.

Syntax: service-enabled <service-name>

Arguments:

service-name - Service name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  service-enabled nginx

`service-works`

Checks if service is works.

Syntax: service-works <service-name>

Arguments:

service-name - Service name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  service-works nginx

`wait-service`

Waits for service start.

Syntax: wait-service <service-name> <timeout>

Arguments:

service-name - Service name (String)
timeout - Timeout in seconds (Float) [Optional | 15 seconds]

Negative form: Yes

Example:

command "systemctl start nginx" "Start Nginx service"
  wait-service nginx 5

HTTP

`http-status`

Makes HTTP request and checks status code.

Syntax: http-status <method> <url> <code> [payload]

Arguments:

method - Method (String)
url - URL (String)
code - Status code (Integer)
payload - Request payload (String) [Optional]

Negative form: Yes

Examples:

command "-" "Make HTTP request"
  http-status GET "http://127.0.0.1:19999" 200

command "-" "Make HTTP request"
  http-status PUT "http://127.0.0.1:19999" 200 '{"id":103}'

`http-header`

Makes HTTP request and checks response header value.

Syntax: http-header <method> <url> <header-name> <header-value> [payload]

Arguments:

method - Method (String)
url - URL (String)
header-name - Header name (String)
header-value - Header value (String)
payload - Request payload (String) [Optional]

Negative form: Yes

Examples:

command "-" "Make HTTP request"
  http-header GET "http://127.0.0.1:19999" strict-transport-security "max-age=32140800"

command "-" "Make HTTP request"
  http-header PUT "http://127.0.0.1:19999" x-request-status "OK" '{"id":103}'

`http-contains`

Makes HTTP request and checks response data for some substring.

Syntax: http-contains <method> <url> <substr> [payload]

Arguments:

method - Method (String)
url - URL (String)
substr - Substring for search (String)
payload - Request payload (String) [Optional]

Negative form: Yes

Example:

command "-" "Make HTTP request"
  http-contains GET "http://127.0.0.1:19999/info" "version: 1"

`http-json`

Makes HTTP request and allows to check JSON value.

Syntax: http-json <method> <url> <query> <value>

Arguments:

method - Method (String)
url - URL (String)
query - Query (String)
value - Value for check (String)

Negative form: Yes

Example:

command "-" "Make HTTP request and check domain info"
  http-json GET https://dns.google/resolve?name=andy.one Question[0].name andy.one.

`http-set-auth`

Sets username and password for Basic Auth.

Notice that auth data will be set only for current command scope.

Syntax: http-set-auth <username> <password>

Arguments:

username - User name (String)
password - Password (String)

Negative form: No

Example:

command "-" "Make HTTP request with auth"
  http-set-auth admin test1234
  http-status GET "http://127.0.0.1:19999" 200

command "-" "Make HTTP request without auth"
  http-status GET "http://127.0.0.1:19999" 403

`http-set-header`

Sets request header.

Notice that header will be set only for current command scope.

Syntax: http-set-header <header-name> <header-value>

Arguments:

header-name - Header name (String)
header-value - Header value (String)

Negative form: No

Example:

command "-" "Make HTTP request"
  http-set-header Accept application/vnd.myapp.v3+json
  http-status GET "http://127.0.0.1:19999" 200

Libraries

`lib-loaded`

Checks if the library is loaded to the dynamic linker.

Syntax: lib-loaded <glob>

Arguments:

glob - Shared library file name glob (String)

Negative form: Yes

Example:

command "-" "Check environment"
  lib-loaded libreadline.so.*

`lib-header`

Checks if library header files are present on the system.

Syntax: lib-header <lib>

Arguments:

lib - Library name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  lib-header expat

`lib-config`

Checks if the library has a valid configuration file for pkg-config.

Syntax: lib-config <lib>

Arguments:

lib - Library name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  lib-config expat

`lib-exist`

Checks if library file is exist in libraries directory.

Syntax: lib-exist <filename>

Arguments:

filename - Library file name (String)

Negative form: Yes

Example:

command "-" "Check environment"
  lib-exist libc.so.1
  lib-exist libc_nonshared.a

`lib-linked`

Checks if binary file has link with given library.

Syntax: lib-linked <binary> <glob>

Arguments:

binary - Path to binary file (String)
glob - Shared library file name glob (String)

Negative form: Yes

Example:

command "-" "Check linking"
  lib-linked /usr/bin/myapp libc.so.*

`lib-rpath`

Checks if binary file has rpath/runpath/runpath field with given path.

Syntax: lib-rpath <binary> <path>

Arguments:

binary - Path to binary file (String)
path - Path to directory (String)

Negative form: Yes

Example:

command "-" "Check rpath"
  lib-rpath /usr/bin/myapp /usr/share/myapp/lib64

`lib-soname`

Checks if shared library file has soname field with given value.

Syntax: lib-soname <lib> <glob>

Arguments:

lib - Path to shared library file (String)
glob - Shared library soname glob (String)

Negative form: Yes

Example:

command "-" "Check library soname"
  lib-soname /usr/lib64/libz.so.1.2.11 libz.so.1

`lib-exported`

Checks if shared library exported a symbol.

▲ You can use script bibop-so-exported for generating these tests.

Syntax: lib-exported <lib> <symbol>

Arguments:

lib - Name or path to shared library file (String)
symbol - Exported symbol (String)

Negative form: Yes

Example:

command "-" "Check symbols exported by libcurl.so.4"
  lib-exported libcurl.so.4 curl_url_dup
  lib-exported libcurl.so.4 curl_url_get
  lib-exported libcurl.so.4 curl_url_set
  lib-exported libcurl.so.4 curl_version
  lib-exported libcurl.so.4 curl_version_info

command "-" "Check symbols exported by mylib.so"
  lib-exported /srv/myapp/libs/myapp-lib.so suppa_duppa_method

Python

`python2-package`

Checks if a given Python 2.x package could be loaded.

Syntax: python-package <name>

Arguments:

name - Module name (String)

Negative form: No

Example:

command "-" "Check Python package loading"
  python-package certifi

`python3-package`

Checks if a given Python 3.x package could be loaded.

Syntax: python3-package <name>

Arguments:

name - Module name (String)

Negative form: No

Example:

command "-" "Check Python 3 package loading"
  python3-package certifi

Examples

# Bibop recipe for MkCryptPasswd

pkg mkcryptpasswd

fast-finish yes

var password MyPassword1234
var salt SALT1234
var salt_length 9

command "mkcryptpasswd -s" "Generate basic hash for password"
  expect "Please enter password:"
  print "{password}"
  expect "Hash: "
  exit 0

command "mkcryptpasswd -s -sa {salt}" "Generate hash for password with predefined salt"
  expect "Please enter password"
  print "{password}"
  expect "$6${salt}$lTxNu4.6r/j81sirgJ.s9ai8AA3tJdp67XBWLFiE10tIharVYtzRJ9eJ9YEtQsiLzVtg94GrXAYjf40pWEEg7/"
  exit 0

command "mkcryptpasswd -s -sa {salt} -1" "Generate MD5 hash for password with predefined salt"
  expect "Please enter password"
  print "{password}"
  expect "$1${salt}$zIPLJYODoLlesdP3bf95S1"
  exit 0

command "mkcryptpasswd -s -sa {salt} -5" "Generate SHA256 hash for password with predefined salt"
  expect "Please enter password"
  print "{password}"
  expect "$5${salt}$HOV.9Dkp4HSDzcfizNDG7x5ST4e74zcezvCJ8BWHuK8"
  exit 0

command "mkcryptpasswd -s -S" "Return error if password is too weak"
  expect "Please enter password"
  print "password"
  expect "Password is too weak: it is based on a dictionary word"
  print "password"
  expect "Password is too weak: it is based on a dictionary word"
  print "password"
  expect "Password is too weak: it is based on a dictionary word"
  !exit 0

command "mkcryptpasswd --abcd" "Return error about unsupported argument"
  expect "Error! You used unsupported argument --abcd. Please check command syntax."
  !exit 0

# Bibop recipe for webkaos (CentOS 7+)

pkg webkaos webkaos-debug webkaos-nginx webkaos-module-brotli webkaos-module-naxsi

require-root yes
unsafe-actions yes
https-skip-verify yes

var service_name webkaos
var user_name webkaos
var prefix_dir /etc/webkaos
var config {prefix_dir}/webkaos.conf
var binary /usr/sbin/webkaos
var modules_config {prefix_dir}/modules.conf
var modules_dir /usr/share/webkaos/modules
var pid_file /var/run/webkaos.pid
var ssl_dir {prefix_dir}/ssl
var dh_param {ssl_dir}/dhparam.pem
var log_dir /var/log/webkaos

var lua_ver 2.1.0-beta3
var lua_dir /usr/share/webkaos/luajit/share/luajit-{lua_ver}

command "-" "System environment validation"
  user-exist {user_name}
  group-exist {user_name}
  service-present {service_name}
  service-enabled {service_name}
  exist {config}
  exist {log_dir}

command "-" "Debug version"
  exist {binary}.debug
  service-present webkaos-debug

command "-" "Check linking with LuaJIT"
  lib-rpath {binary} /usr/share/webkaos/luajit/lib
  lib-linked {binary} "libluajit-5.1.so.*"

command "-" "Check Resty core and lrucache"
  dir {lua_dir}/ngx
  dir {lua_dir}/ngx/ssl
  dir {lua_dir}/resty
  dir {lua_dir}/resty/core
  dir {lua_dir}/resty/lrucache

  exist {lua_dir}/ngx/balancer.lua
  exist {lua_dir}/ngx/base64.lua
  exist {lua_dir}/ngx/errlog.lua
  exist {lua_dir}/ngx/ocsp.lua
  exist {lua_dir}/ngx/pipe.lua
  exist {lua_dir}/ngx/process.lua
  exist {lua_dir}/ngx/re.lua
  exist {lua_dir}/ngx/req.lua
  exist {lua_dir}/ngx/resp.lua
  exist {lua_dir}/ngx/semaphore.lua
  exist {lua_dir}/ngx/ssl.lua
  exist {lua_dir}/ngx/ssl/session.lua
  exist {lua_dir}/resty/core.lua
  exist {lua_dir}/resty/lrucache.lua
  exist {lua_dir}/resty/core/base.lua
  exist {lua_dir}/resty/core/base64.lua
  exist {lua_dir}/resty/core/ctx.lua
  exist {lua_dir}/resty/core/exit.lua
  exist {lua_dir}/resty/core/hash.lua
  exist {lua_dir}/resty/core/misc.lua
  exist {lua_dir}/resty/core/ndk.lua
  exist {lua_dir}/resty/core/phase.lua
  exist {lua_dir}/resty/core/regex.lua
  exist {lua_dir}/resty/core/request.lua
  exist {lua_dir}/resty/core/response.lua
  exist {lua_dir}/resty/core/shdict.lua
  exist {lua_dir}/resty/core/socket.lua
  exist {lua_dir}/resty/core/time.lua
  exist {lua_dir}/resty/core/uri.lua
  exist {lua_dir}/resty/core/utils.lua
  exist {lua_dir}/resty/core/var.lua
  exist {lua_dir}/resty/core/worker.lua
  exist {lua_dir}/resty/lrucache/pureffi.lua

  mode {lua_dir}/ngx/balancer.lua 644
  mode {lua_dir}/ngx/base64.lua 644
  mode {lua_dir}/ngx/errlog.lua 644
  mode {lua_dir}/ngx/ocsp.lua 644
  mode {lua_dir}/ngx/pipe.lua 644
  mode {lua_dir}/ngx/process.lua 644
  mode {lua_dir}/ngx/re.lua 644
  mode {lua_dir}/ngx/req.lua 644
  mode {lua_dir}/ngx/resp.lua 644
  mode {lua_dir}/ngx/semaphore.lua 644
  mode {lua_dir}/ngx/ssl.lua 644
  mode {lua_dir}/ngx/ssl/session.lua 644
  mode {lua_dir}/resty/core.lua 644
  mode {lua_dir}/resty/lrucache.lua 644
  mode {lua_dir}/resty/core/base.lua 644
  mode {lua_dir}/resty/core/base64.lua 644
  mode {lua_dir}/resty/core/ctx.lua 644
  mode {lua_dir}/resty/core/exit.lua 644
  mode {lua_dir}/resty/core/hash.lua 644
  mode {lua_dir}/resty/core/misc.lua 644
  mode {lua_dir}/resty/core/ndk.lua 644
  mode {lua_dir}/resty/core/phase.lua 644
  mode {lua_dir}/resty/core/regex.lua 644
  mode {lua_dir}/resty/core/request.lua 644
  mode {lua_dir}/resty/core/response.lua 644
  mode {lua_dir}/resty/core/shdict.lua 644
  mode {lua_dir}/resty/core/socket.lua 644
  mode {lua_dir}/resty/core/time.lua 644
  mode {lua_dir}/resty/core/uri.lua 644
  mode {lua_dir}/resty/core/utils.lua 644
  mode {lua_dir}/resty/core/var.lua 644
  mode {lua_dir}/resty/core/worker.lua 644
  mode {lua_dir}/resty/lrucache/pureffi.lua 644

command "-" "Nginx compatibility package"
  exist /etc/nginx
  exist /var/log/nginx
  exist /etc/nginx/nginx.conf
  exist /usr/sbin/nginx
  service-present nginx
  service-present nginx-debug

command "-" "Original configuration backup"
  backup {config}
  backup {modules_config}

command "-" "Add modules configuration"
  copy modules.conf {modules_config}

command "-" "Replace original configuration"
  copy webkaos.conf {config}

command "-" "Add test DH params file"
  copy dhparam.pem {dh_param}
  chmod {dh_param} 600

command "-" "Add self-signed certificate"
  copy ssl.key {ssl_dir}/ssl.key
  copy ssl.crt {ssl_dir}/ssl.crt
  chmod {ssl_dir}/ssl.key 600
  chmod {ssl_dir}/ssl.crt 600

command "-" "Clear old log files"
  touch {log_dir}/access.log
  touch {log_dir}/error.log
  truncate {log_dir}/access.log
  truncate {log_dir}/error.log

command "-" "Check brotli module"
  exist {prefix_dir}/xtra/brotli.conf
  exist {modules_dir}/ngx_http_brotli_filter_module.so
  exist {modules_dir}/ngx_http_brotli_static_module.so
  mode {prefix_dir}/xtra/brotli.conf 644
  mode {modules_dir}/ngx_http_brotli_filter_module.so 755
  mode {modules_dir}/ngx_http_brotli_static_module.so 755

command "-" "Check NAXSI module"
  exist {prefix_dir}/naxsi_core.rules
  exist {modules_dir}/ngx_http_naxsi_module.so
  mode {prefix_dir}/naxsi_core.rules 644
  mode {modules_dir}/ngx_http_naxsi_module.so 755

command "systemctl start {service_name}" "Start service"
  wait-pid {pid_file} 5
  service-works {service_name}

command "-" "Make HTTP requests"
  http-status GET "http://127.0.0.1" 200
  http-header GET "http://127.0.0.1" server webkaos
  http-contains GET "http://127.0.0.1/lua" "LUA MODULE WORKS"
  !empty {log_dir}/access.log
  truncate {log_dir}/access.log

command "-" "Make HTTPS requests"
  http-status GET "https://127.0.0.1" 200
  http-header GET "https://127.0.0.1" server webkaos
  http-contains GET "https://127.0.0.1/lua" "LUA MODULE WORKS"
  !empty {log_dir}/access.log
  truncate {log_dir}/access.log

command "-" "Save PID file checksum"
  checksum-read {pid_file} pid_sha

command "service {service_name} upgrade" "Binary upgrade"
  wait 3
  exist {pid_file}
  service-works {service_name}
  http-status GET "http://127.0.0.1" 200
  !checksum {pid_file} {pid_sha}

command "-" "Update configuration to broken one"
  copy broken.conf {config}

command "service {service_name} check" "Broken config check"
  !exit 0
  !empty {log_dir}/error.log

command "service {service_name} reload" "Broken config reload"
  !exit 0

command "service {service_name} restart" "Restart with broken config"
  !exit 0

command "-" "Restore working configuration"
  copy webkaos.conf {config}

command "service {service_name} reload" "Reload with original config"
  exit 0

command "systemctl stop {service_name}" "Stop service"
  !wait-pid {pid_file} 5
  !service-works {service_name}
  !connect tcp ":http"
  !exist {pid_file}

command "-" "Clear old log files"
  truncate {log_dir}/access.log
  truncate {log_dir}/error.log

command "systemctl start {service_name}-debug" "Start debug version of service"
  wait-pid {pid_file} 5
  service-works {service_name}-debug

+command "-" "Make HTTP requests"
  http-status GET "http://127.0.0.1" 200
  http-header GET "http://127.0.0.1" server webkaos
  http-contains GET "http://127.0.0.1/lua" "LUA MODULE WORKS"
  !empty {log_dir}/access.log
  truncate {log_dir}/access.log

+command "-" "Make HTTPS requests"
  http-status GET "https://127.0.0.1" 200
  http-header GET "https://127.0.0.1" server webkaos
  http-contains GET "https://127.0.0.1/lua" "LUA MODULE WORKS"
  !empty {log_dir}/access.log
  truncate {log_dir}/access.log

+command "systemctl stop {service_name}-debug" "Stop debug version of service"
  !wait-pid {pid_file} 5
  !service-works {service_name}-debug
  !connect tcp ":http"
  !exist {pid_file}

command:teardown "-" "Configuration restore"
  backup-restore {config}
  backup-restore {modules_config}

command:teardown "-" "DH param cleanup"
  remove {dh_param}

command:teardown "-" "Self-signed certificate cleanup"
  remove {ssl_dir}/ssl.key
  remove {ssl_dir}/ssl.crt

More working examples you can find in our repository with recipes for our RPM packages.

Uh oh!

FilesExpand file tree

COOKBOOK.md

Latest commit

History

COOKBOOK.md

File metadata and controls

Recipe Syntax

Comments

Data types

Global keywords

pkg

unsafe-actions

require-root

fast-finish

lock-workdir

unbuffer

https-skip-verify

delay

command

Variables

Actions

Common

exit

wait

template

Input/Output

expect

print

wait-output

output-match

output-contains

output-empty

output-trim

Filesystem

chdir

mode

owner

exist

link

readable

writable

executable

dir

empty

empty-dir

checksum

checksum-read

file-contains

copy

move

touch

mkdir

remove

chmod

chown

truncate

cleanup

backup

backup-restore

System

process-works

wait-pid

wait-fs

wait-connect

connect

app

signal

env

env-set

Users/Groups

user-exist

user-id

user-gid

user-group

user-shell

user-home

group-exist

group-id

Services

`pkg`

`unsafe-actions`

`require-root`

`fast-finish`

`lock-workdir`

`unbuffer`

`https-skip-verify`

`delay`

`command`

`exit`

`wait`

`template`

`expect`

`print`

`wait-output`

`output-match`

`output-contains`

`output-empty`

`output-trim`

`chdir`

`mode`

`owner`

`exist`

`link`

`readable`

`writable`

`executable`

`dir`

`empty`

`empty-dir`

`checksum`

`checksum-read`

`file-contains`

`copy`

`move`

`touch`

`mkdir`

`remove`

`chmod`

`chown`

`truncate`

`cleanup`

`backup`

`backup-restore`

`process-works`

`wait-pid`

`wait-fs`

`wait-connect`

`connect`

`app`

`signal`

`env`

`env-set`

`user-exist`

`user-id`

`user-gid`

`user-group`

`user-shell`

`user-home`

`group-exist`

`group-id`

`service-present`

`service-enabled`

`service-works`

`wait-service`

`http-status`

`http-header`

`http-contains`

`http-json`

`http-set-auth`

`http-set-header`

`lib-loaded`

`lib-header`

`lib-config`

`lib-exist`

`lib-linked`

`lib-rpath`

`lib-soname`

`lib-exported`

`python2-package`