Driver `app.simple`

Minimal configlet:

[app#1]
type = simple
start = /usr/bin/sleep 600

Minimal setup command:

om test/svc/foo set \
	--kw="type=simple" \
	--kw="start=/usr/bin/sleep 600"

Supported keywords:

blocking_post_provision
blocking_post_start
blocking_post_stop
blocking_post_unprovision
blocking_pre_provision
blocking_pre_start
blocking_pre_stop
blocking_pre_unprovision
check
check_timeout
comment
configs_environment
cwd
desc
disable
encap
environment
group
info
info_timeout
limit_as
limit_core
limit_cpu
limit_data
limit_fsize
limit_memlock
limit_nofile
limit_nproc
limit_rss
limit_stack
limit_vmem
monitor
netns
optional
pg_blkio_weight
pg_cpu_burst
pg_cpu_quota
pg_cpu_shares
pg_cpus
pg_mem_high
pg_mem_limit
pg_mem_oom_control
pg_mem_swappiness
pg_mems
pg_pids_max
pg_vmem_limit
post_provision
post_start
post_stop
post_unprovision
pre_provision
pre_start
pre_stop
pre_unprovision
provision
provision_requires
restart
restart_delay
retcodes
script
secrets_environment
shared
standby
start
start_requires
stat_timeout
status_log
stop
stop_requires
stop_timeout
subset
tags
timeout
type
umask
unprovision
unprovision_requires
user

Keyword `blocking_post_provision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource provision action.

Errors interrupt the action.

This trigger is only executed on leaders.

Keyword `blocking_post_start`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource start action.

Errors interrupt the action.

Keyword `blocking_post_stop`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource stop action.

Errors interrupt the action.

Keyword `blocking_post_unprovision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute after the resource unprovision action.

Errors interrupt the action.

This trigger is only executed on leaders.

Keyword `blocking_pre_provision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource provision action.

Errors interrupt the action.

Keyword `blocking_pre_start`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource start action.

Errors interrupt the action.

Keyword `blocking_pre_stop`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource stop action.

Errors interrupt the action.

Keyword `blocking_pre_unprovision`

required:    false
scopable:    true
rbac:        Triggers require the root grant.

Description:

A command or script to execute before the resource unprovision action.

Errors interrupt the action.

Keyword `check`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

check=/usr/local/bin/check

Description:

true

Execute the script command with status argument on status action.
false

Do nothing on status action.
<shlex expression>

Execute this command on status action.

If not set, the driver will lookup the process it started.

Keyword `check_timeout`

required:    false
scopable:    true
convert:     duration
rbac:        This driver group requires the root grant.

Example:

check_timeout=180

Description:

Wait for <duration> before declaring the app launcher status action a failure.

Takes precedence over timeout.

If neither timeout nor check_timeout is set, the agent waits indefinitely for the app launcher to return.

A timeout can be coupled with optional=true to not abort a service instance status when an app launcher did not return.

Keyword `comment`

required:    false
scopable:    false
rbac:        This driver group requires the root grant.

Description:

A free form text describing the role of the object, of the node, or of the section it is set in.

The keyword is accepted in any section, so the DEFAULT section can document a configuration as a whole, and a resource, pool, heartbeat, array or network section can document itself.

The agent does not interpret the value.

Keyword `configs_environment`

required:    false
scopable:    true
convert:     shlex
rbac:        This driver group requires the root grant.

Example:

configs_environment=PORT=http/port webapp/app1* {name}/* {name}-debug/settings

Description:

A whitespace-separated list of <var>=<cfg name>/<key path> or <cfg name>/<key matcher>.

If the cfg or config key doesn’t exist then start and stop actions on the resource will fail with a non 0 exit code.

A shell expression splitter is applied, so double quotes can be around <cfg name>/<key path> only or whole <var>=<cfg name>/<key path>.

Example with,

<ns>/cfg/nginx a config having a user key with value user1.
<ns>/cfg/cfg1 a config having a key1 key with value val1.

configs_environment = NGINX_USER=nginx/user cfg1/* creates the following variables in the process execution environment:

NGINX_USER=user1
key1=val1

Keyword `cwd`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Description:

Change the working directory to the specified location instead of the default <pathtmp>.

Keyword `desc`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

desc=rpc.idmapd

Description:

A custom resource label. This is useful to keep rid simple like app#1 but still have the label to help describe the role of the resource.

Keyword `disable`

required:    false
scopable:    true
convert:     bool
rbac:        This driver group requires the root grant.

Description:

A disabled resource will be ignored on start, stop, provision and unprovision actions.

A disabled resource status is n/a.

If set in the DEFAULT section of an object, the object is disabled and ignores start, stop, shutdown, provision and unprovision actions.

These actions immediately return success.

om <path> disable sets DEFAULT.disable=true.

om <path> enable sets DEFAULT.disable=false.

Note: The enable and disable actions preserve the individual resource disable state.

Keyword `encap`

required:    false
scopable:    false
convert:     bool
rbac:        This driver group requires the root grant.

Description:

Set to true to ignore this resource in the nodes context and consider it in the encapnodes context. The resource is thus handled by agents deployed in the service containers.

Keyword `environment`

required:    false
scopable:    true
convert:     shlex
rbac:        This driver group requires the root grant.

Example:

environment=CRT=cert1/server.crt PEM=cert1/server.pem

Description:

A whitespace-separated list of <var>=<value>.

A shell expression splitter is applied, so double quotes can be around <value> only or whole <var>=<value>.

Keyword `group`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Description:

If the binary is owned by the root user, run it as the specified group instead of root.

Keyword `info`

required:    false
scopable:    true
default:     false
rbac:        This driver group requires the root grant.

Description:

Plug a key-value source into the instance resource info.

true

Execute the script command with the info argument on instance info --refresh.
false

Do nothing on instance info --refresh.
<shlex expression>

Execute this command on instance info --refresh.

Stdout lines must contain only one key:value.

Invalid lines are dropped. A line whose value contains a :, like a url or a timestamp, has more than one separator and is dropped too.

The command must exit 0: a failure aborts the refresh of the whole instance, which then reports no key-value at all.

Keyword `info_timeout`

required:    false
scopable:    true
convert:     duration
rbac:        This driver group requires the root grant.

Example:

info_timeout=180

Description:

Wait for <duration> before declaring the app launcher info action a failure.

Takes precedence over timeout.

If neither timeout nor info_timeout is set, the agent waits indefinitely for the app launcher to return.

A timeout can be coupled with optional=true to not abort a service instance info when an app launcher did not return.

Keyword `limit_as`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the total virtual memory that can be in use by a process (unit bytes) (same as limit_vmem).

When both limit_vmem and limit_as is used, the max value is chosen.

Keyword `limit_core`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the largest core dump size that can be produced (unit byte).

Keyword `limit_cpu`

required:    false
scopable:    true
convert:     duration
rbac:        This driver group requires the root grant.

Example:

limit_cpu=30s

Description:

The limit on CPU time (duration).

Keyword `limit_data`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the data segment size of a process (unit byte).

Keyword `limit_fsize`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the largest file that can be created (unit byte).

Keyword `limit_memlock`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on how much memory a process can lock with mlock(2) (unit byte, no solaris support).

Keyword `limit_nofile`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the number files a process can have open at once.

Keyword `limit_nproc`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the number of processes this user can have at one time, no solaris support.

Keyword `limit_rss`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the total physical memory that can be in use by a process (unit byte, no solaris support).

Keyword `limit_stack`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the stack size of a process (unit bytes).

Keyword `limit_vmem`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Description:

The limit on the total virtual memory that can be in use by a process (unit bytes).

Keyword `monitor`

required:    false
scopable:    true
convert:     bool
rbac:        This driver group requires the root grant.

Description:

A resource with monitor=true will trigger the monitor_action (crash or reboot the node, freezestop or switch the service) if:

The resource is down.
The instance has local_expect=started in its daemon monitor data, which means the daemon considers this instance is and should remain started.
All restart tentatives failed.

Keyword `netns`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

netns=ip#0

Description:

Start the application process in a netns another resource is known to use.

For example a service with a cni-type ip#0 resource that doesn’t set a netns value will create a private netns named after the object id. A app#0 resource can use this netns by setting app#0.netns=ip#0.

The starter program is executed via ip netns exec.

Keyword `optional`

required:    false
scopable:    true
convert:     bool
rbac:        This driver group requires the root grant.

Description:

Action errors on optional resources are logged but do not interrupt the action sequence.

The status of optional resources is not included in the instance availability status but is considered in the overall status.

The status of task and sync resources is always included in the overall status, regardless of whether they are marked as optional.

Resources tagged as noaction are considered optional by default.

Dump filesystems are a typical use case for optional=true.

Keyword `pg_blkio_weight`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

pg_blkio_weight=50

Description:

Block IO relative weight. Value: between 10 and 1000.

The kernel default is 100.

Setting this keyword to default puts the capping back where a node that never capped anything leaves it. Removing the keyword does not: what was written stays written, whether om wrote it or something else did.

Keyword `pg_cpu_burst`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

pg_cpu_burst=20%

Description:

The cpu time the group banks under its quota, and spends above it.

It is the time the processes of the group may bank while under their pg_cpu_quota, and spend above it in a short spike, in the notation of pg_cpu_quota: 20% lets the group run a fifth of a cpu above its quota during a period, out of what it left unused before.

It serves a latency-sensitive service capped tightly: a request arriving after an idle spell is served at the speed of the burst, rather than throttled for the rest of the period. Over a longer time the group still uses no more than its quota.

It needs pg_cpu_quota, and cannot exceed it: the kernel refuses a burst larger than the quota. Only the unified cgroup hierarchy has it.

Keyword `pg_cpu_quota`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

pg_cpu_quota=50%@all

Description:

The percentage of cpu time the processes of the group may use.

Accepted expressions:

50% Half of one cpu.
50%@all Half of every cpu the node has.
10%@2 A tenth of two cpus.

Unlike pg_cpu_shares, which only arbitrates when the node is cpu-bound, a quota caps the group whether or not the node is busy.

Keyword `pg_cpu_shares`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Example:

pg_cpu_shares=512

Description:

The share of cpu the group gets when the node is cpu-bound.

The share is relative to the other groups.

The actual percentile depends on the shares allowed to the other services. Unset, the kernel default is used, which usually is 1024 shares.

Keyword `pg_cpus`

required:    false
scopable:    true
depends:     create_pg=true
rbac:        This driver group requires the root grant.

Example:

pg_cpus=0-2

Description:

The cpus the processes of the group may run on.

Cpus are specified as list or range : 0,1,2 or 0-2.

Keyword `pg_mem_high`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Example:

pg_mem_high=384m

Description:

The memory past which the kernel throttles the group, in bytes.

Past it, the kernel slows the processes of the group down, reclaiming their memory and throttling their allocations.

Unlike pg_mem_limit, reaching it does not wake the Out-Of-Memory killer: a group above it keeps running, slower, while the kernel reclaims. Set below pg_mem_limit, it gives a process growing too much the time to be noticed, or to shrink, before it is killed.

It is a soft limit, so it is not what a memory claim counts: the claim counts pg_mem_limit. Only the unified cgroup hierarchy has it.

Keyword `pg_mem_limit`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Example:

pg_mem_limit=512m

Description:

The memory the processes of the group may use, in bytes.

The Out-Of-Memory killer is triggered in case of tresspassing.

Keyword `pg_mem_oom_control`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

pg_mem_oom_control=1

Description:

Whether the Out of Memory killer runs for the group: 0 enables it.

It is a flag (0 or 1) enabling or disabling the Out of Memory killer for the processes of the group.

If enabled (0), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
If disabled (1), tasks are allowed to continue to try allocating memory, stressing the system.

The OOM killer is enabled by default in every cgroup using the memory controller.

This keyword caps nothing on a node holding the unified cgroup hierarchy, which has no memory.oom_control: that file is of the v1 hierarchy. Setting it there is warned about, and ignored.

Keyword `pg_mem_swappiness`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

pg_mem_swappiness=40

Description:

Set a swappiness percentile value for the process group.

This keyword caps nothing on a node holding the unified cgroup hierarchy, which has no memory.swappiness: that file is of the v1 hierarchy. Setting it there is warned about, and ignored.

Keyword `pg_mems`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

pg_mems=0-2

Description:

The memory nodes the processes of the group may allocate from.

Memory nodes are specified as list or range : 0,1,2 or 0-2.

Keyword `pg_pids_max`

required:    false
scopable:    true
rbac:        This driver group requires the root grant.

Example:

pg_pids_max=512

Description:

The most processes and threads the group may run at once.

A fork beyond it fails in the process that asked for it, and nothing else of the node is touched: it is what keeps a runaway fork loop from exhausting the process table of the node.

Keyword `pg_vmem_limit`

required:    false
scopable:    true
convert:     size
rbac:        This driver group requires the root grant.

Example:

pg_vmem_limit=1g

Description:

The memory plus swap the processes of the group may use, in bytes.

The Out-Of-Memory killer is triggered in case of tresspassing. The specified value must be greater than pg_mem_limit.