Managedfile
Files osapi writes on a host and keeps a record of.
osapi behavior get --name managedfile and osapi behavior method get show the
same.
Behavior
| Name | managedfile |
| Description | Files osapi writes on a host and keeps a record of |
| Placement | node |
| Internal | yes |
| API | no |
| CLI | no |
| Next | no |
| Platforms | debian |
| Sudo | chown |
| Runs | stat |
| Writes | * |
| Keeps state | yes |
| Uses | none |
| Used by | netplan, service, sysctl |
Methods (3)
| NAME | VERB | ROUTE | PERMISSION | DESCRIPTION |
|---|---|---|---|---|
| get | read | - | - | Read the record of a file osapi wrote |
| update | write | - | - | Write a file and keep a record of it |
| delete | write | - | - | Remove a file osapi wrote and stop managing it |
Types (3)
| NAME | INPUT | OUTPUT |
|---|---|---|
| get | GetInput { path* } | Record { path, sha256, metadata, undeployed } |
| update | UpdateInput { path*, content*, mode, owner, group, secret, metadata } | Result { path, changed } |
| delete | DeleteInput { path* } | Result { path, changed } |
Settings (0)
None. Declare them with behavior.Config.
Telemetry
| Span | behavior.managedfile.<method> |
| Child spans | 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 | path (get, update, delete) |
Method get
| Name | get |
| Verb | read |
| Description | Read the record of a file osapi wrote |
| Route | other behaviors only; it is not served |
| Input type | GetInput |
| Output type | Record |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| path | string | yes | pattern ^/ | Absolute path of the file |
Output (4)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| path | string | Absolute path of the file |
| sha256 | string | Checksum of the content osapi wrote |
| metadata | object | What the caller keeps in the record |
| undeployed | boolean | Whether osapi has stopped managing the file |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A file osapi wrote | path=/etc/osapi/example.conf | path=/etc/osapi/example.conf, sha256=b6ac5bc39377e44ee783dff946f6703a994f5eb31a438e69dc0735b40060d2e8, metadata=map[setting:on], undeployed=false |
| A file osapi stopped managing | path=/etc/osapi/example.conf | path=/etc/osapi/example.conf, sha256=b6ac5bc39377e44ee783dff946f6703a994f5eb31a438e69dc0735b40060d2e8, metadata=map[setting:on], undeployed=true |
Method update
| Name | update |
| Verb | write |
| Description | Write a file and keep a record of it |
| Detail | Leaves a file already holding the content alone and reports changed: false, whatever its record says, so a file edited by hand is put back. |
| Route | other behaviors only; it is not served |
| Input type | UpdateInput |
| Output type | Result |
Input (7)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| path | string | yes | pattern ^/ | Absolute path of the file |
| content | string | yes | The file's whole content | |
| mode | string | no | pattern ^[0-7]{3,4}$ | Permissions in octal, such as 0600; 0644 when empty |
| owner | string | no | pattern ^[a-z_][a-z0-9_-]*$?$ | User that owns the file; left as written when empty |
| group | string | no | pattern ^[a-z_][a-z0-9_-]*$?$ | Group that owns the file; left as written when empty |
| secret | boolean | no | The content is a secret: its record keeps no checksum of it | |
| metadata | object | no | What the caller keeps in the file's record, such as the setting it holds |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| path | string | Absolute path of the file |
| changed | boolean | Whether the host changed |
Examples (4)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A new file | path=/etc/osapi/example.conf, content=on , mode=, owner=, group=, secret=false, metadata=<nil> | path=/etc/osapi/example.conf, changed=true |
| A secret only root reads | path=/etc/myapp/token, content=s3cret , mode=0600, owner=root, group=root, secret=true, metadata=<nil> | path=/etc/myapp/token, changed=true |
| A file whose mode was changed by hand | path=/etc/osapi/example.conf, content=on , mode=0600, owner=, group=, secret=false, metadata=<nil> | path=/etc/osapi/example.conf, changed=true |
| A file edited by hand | path=/etc/osapi/example.conf, content=on , mode=, owner=, group=, secret=false, metadata=<nil> | path=/etc/osapi/example.conf, changed=true |
Method delete
| Name | delete |
| Verb | write |
| Description | Remove a file osapi wrote and stop managing it |
| Detail | Leaves a file osapi has no record of alone, so it never removes what it did not write. |
| Route | other behaviors only; it is not served |
| Input type | DeleteInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| path | string | yes | pattern ^/ | Absolute path of the file |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| path | string | Absolute path of the file |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A file osapi wrote | path=/etc/osapi/example.conf | path=/etc/osapi/example.conf, changed=true |
| A file osapi never wrote | path=/etc/osapi/example.conf | path=/etc/osapi/example.conf, changed=false |