Sysctl
Kernel parameters, written to sysctl.d files and applied.
osapi behavior get --name sysctl and osapi behavior method get show the
same. Its chain shows each call that its examples
make.
Behavior
| Name | sysctl |
| Description | Kernel parameters, written to sysctl.d files and applied |
| Placement | node |
| Internal | no |
| API | yes |
| CLI | yes |
| Next | no |
| Platforms | debian |
| Sudo | sysctl |
| Runs | none |
| Writes | /etc/sysctl.d/osapi-*.conf |
| Keeps state | no |
| Uses | managedfile |
| Used by | none |
Methods (5)
| NAME | VERB | HTTP | ROUTE | PERMISSION | DESCRIPTION |
|---|---|---|---|---|---|
| list | read | GET | /api/node/{hostname}/sysctl | sysctl:read | List the kernel's parameters and which osapi manages |
| get | read | GET | /api/node/{hostname}/sysctl/{key} | sysctl:read | Get a kernel parameter's current value, and whether osapi manages it |
| create | write | POST | /api/node/{hostname}/sysctl | sysctl:write | Manage a kernel parameter and apply it |
| update | write | PUT | /api/node/{hostname}/sysctl/{key} | sysctl:write | Set a kernel parameter, manage it, and apply it |
| delete | write | DELETE | /api/node/{hostname}/sysctl/{key} | sysctl:write | Stop the management of a kernel parameter |
Types (5)
| NAME | INPUT | OUTPUT |
|---|---|---|
| list | ListInput { prefix } | []Entry { key, value, managed } |
| get | GetInput { key* } | Entry { key, value, managed } |
| create | CreateInput { key*, value* } | MutationResult { key, changed } |
| update | UpdateInput { key*, value* } | MutationResult { key, changed } |
| delete | DeleteInput { key* } | MutationResult { key, changed } |
Settings (1)
| KEY | AGENT FLAG | TYPE | DEFAULT |
|---|---|---|---|
| behaviors.sysctl.dir | --sysctl-dir | string | /etc/sysctl.d |
Telemetry
| Span | behavior.sysctl.<method> |
| Child spans | behavior.managedfile.<method>, exec sysctl, exec chown, exec stat, file.write, file.remove, file.chmod, kv.get, kv.put |
| Metrics | osapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total |
| Attributes | osapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed |
| Recorded inputs | key (get, create, update, delete) |
Method list
| Name | list |
| Verb | read |
| Description | List the kernel's parameters and which osapi manages |
| Detail | Lists every parameter the kernel shows under /proc/sys, with its current value, as sysctl -a does, and marks the ones osapi manages. A prefix, such as net.ipv4, limits the list to that part of the tree. The kernel can lack a parameter that osapi manages, for example when its module is not loaded. Then the list shows the value that osapi wrote. |
| HTTP | GET |
| Route | /api/node/{hostname}/sysctl |
| Permission | sysctl:read |
| Command | osapi client node sysctl list |
| Input type | ListInput |
| Output type | []Entry |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| prefix | string | no | pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ | Only this parameter and the ones under it, such as net.ipv4 |
Output (3)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| key | string | Parameter name |
| value | string | Current runtime value |
| managed | boolean | Whether osapi manages it: a file of its own sets it at boot |
Examples (3)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Every parameter, and which osapi manages | prefix= | [key=kernel.panic, managed=false, value=0] [key=net.ipv4.ip_forward, managed=true, value=1] [key=net.ipv4.ping_group_range, managed=false, value=0 2147483647] |
| One part of the tree | prefix=net.ipv4 | [key=net.ipv4.ip_forward, managed=true, value=1] [key=net.ipv4.ping_group_range, managed=false, value=0 2147483647] |
| A managed parameter the kernel does not have right now | prefix=net.bridge | [key=net.bridge.bridge-nf-call-iptables, managed=true, value=1] |
Method get
| Name | get |
| Verb | read |
| Description | Get a kernel parameter's current value, and whether osapi manages it |
| HTTP | GET |
| Route | /api/node/{hostname}/sysctl/{key} |
| Permission | sysctl:read |
| Command | osapi client node sysctl get |
| Input type | GetInput |
| Output type | Entry |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| key | string | yes | pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]*$, min length 1 | Parameter name, such as net.ipv4.ip_forward |
Output (3)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| key | string | Parameter name |
| value | string | Current runtime value |
| managed | boolean | Whether osapi manages it: a file of its own sets it at boot |
Examples (4)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A parameter osapi manages | key=vm.swappiness | key=vm.swappiness, value=10, managed=true |
| A parameter osapi does not manage | key=vm.swappiness | key=vm.swappiness, value=60, managed=false |
| A value of several fields | key=net.ipv4.ping_group_range | key=net.ipv4.ping_group_range, value=0 2147483647, managed=false |
| A managed parameter the kernel does not have right now | key=net.bridge.bridge-nf-call-iptables | key=net.bridge.bridge-nf-call-iptables, value=1, managed=true |
Method create
| Name | create |
| Verb | write |
| Description | Manage a kernel parameter and apply it |
| Detail | Writes osapi-net.ipv4.ip_forward.conf for net.ipv4.ip_forward to behaviors.sysctl.dir, /etc/sysctl.d by default, and applies it with sysctl -p. It fails when sysctl -p fails, because the value is not set. A second run with the same value changes nothing and reports changed: false. If the kernel has a different value, for example after a failed apply, it applies the value again. |
| HTTP | POST |
| Route | /api/node/{hostname}/sysctl |
| Permission | sysctl:write |
| Command | osapi client node sysctl create |
| Input type | CreateInput |
| Output type | MutationResult |
Input (2)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| key | string | yes | pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]*$, min length 1 | Parameter name, such as net.ipv4.ip_forward |
| value | string | yes | pattern ^[^\r\n]*$ | Value to set |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| key | string | Parameter name |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Turn on IP forwarding | key=net.ipv4.ip_forward, value=1 | key=net.ipv4.ip_forward, changed=true |
Method update
| Name | update |
| Verb | write |
| Description | Set a kernel parameter, manage it, and apply it |
| Detail | The same as create, addressed by the parameter: osapi manages the parameter from then on whether it did before or not. Setting the value it already has reports changed: false. |
| HTTP | PUT |
| Route | /api/node/{hostname}/sysctl/{key} |
| Permission | sysctl:write |
| Command | osapi client node sysctl update |
| Input type | UpdateInput |
| Output type | MutationResult |
Input (2)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| key | string | yes | pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]*$, min length 1 | Parameter name, such as net.ipv4.ip_forward |
| value | string | yes | pattern ^[^\r\n]*$ | Value to set |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| key | string | Parameter name |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Lower swappiness | key=vm.swappiness, value=10 | key=vm.swappiness, changed=true |
| A parameter osapi did not manage | key=vm.swappiness, value=10 | key=vm.swappiness, changed=true |
Method delete
| Name | delete |
| Verb | write |
| Description | Stop the management of a kernel parameter |
| Detail | Removes the file that osapi wrote for it and reloads with sysctl --system. Then a setting for the key in a different file takes effect. If there is no such setting, the parameter keeps its current value until the next reboot. A delete of a parameter that osapi does not manage reports changed: false. |
| HTTP | DELETE |
| Route | /api/node/{hostname}/sysctl/{key} |
| Permission | sysctl:write |
| Command | osapi client node sysctl delete |
| Input type | DeleteInput |
| Output type | MutationResult |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| key | string | yes | pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]*$, min length 1 | Parameter name, such as net.ipv4.ip_forward |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| key | string | Parameter name |
| changed | boolean | Whether the host changed |
Examples (3)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Remove a parameter | key=vm.swappiness | key=vm.swappiness, changed=true |
| A parameter osapi does not manage | key=vm.swappiness | key=vm.swappiness, changed=false |
| A parameter osapi already stopped managing | key=vm.swappiness | key=vm.swappiness, changed=false |