Service
The systemd services of the host. osapi behavior get --name service and
osapi behavior method get show the same. Its chain
shows each call that its examples make.
Behavior
| Name | service |
| Description | The systemd services of the host |
| Placement | node |
| Internal | no |
| API | yes |
| CLI | yes |
| Next | no |
| Platforms | debian, linux |
| Sudo | none |
| Runs | systemctl |
| Writes | /etc/systemd/system/osapi-*.service |
| Keeps state | no |
| Uses | object, managedfile |
| Used by | none |
Methods (10)
| NAME | VERB | HTTP | ROUTE | PERMISSION | DESCRIPTION |
|---|---|---|---|---|---|
| list | read | GET | /api/node/{hostname}/service | service:read | List the services of the host |
| get | read | GET | /api/node/{hostname}/service/{name} | service:read | Get one service |
| create | write | POST | /api/node/{hostname}/service | service:write | Deploy a service |
| update | write | PUT | /api/node/{hostname}/service/{name} | service:write | Deploy a new unit file for a service |
| delete | write | DELETE | /api/node/{hostname}/service/{name} | service:write | Remove a service that osapi deployed |
| start | write | POST | /api/node/{hostname}/service/{name}/start | service:write | Start a service that osapi deployed |
| stop | write | POST | /api/node/{hostname}/service/{name}/stop | service:write | Stop a service that osapi deployed |
| restart | write | POST | /api/node/{hostname}/service/{name}/restart | service:write | Restart a service that osapi deployed |
| enable | write | POST | /api/node/{hostname}/service/{name}/enable | service:write | Make a service that osapi deployed start at boot |
| disable | write | POST | /api/node/{hostname}/service/{name}/disable | service:write | Make a service that osapi deployed not start at boot |
Types (10)
| NAME | INPUT | OUTPUT |
|---|---|---|
| list | ListInput | []Entry { name, state, enabled, description } |
| get | GetInput { name* } | Entry { name, state, enabled, description } |
| create | CreateInput { name*, object* } | Result { name, changed } |
| update | UpdateInput { name*, object* } | Result { name, changed } |
| delete | DeleteInput { name* } | Result { name, changed } |
| start | StartInput { name* } | Result { name, changed } |
| stop | StopInput { name* } | Result { name, changed } |
| restart | RestartInput { name* } | Result { name, changed } |
| enable | EnableInput { name* } | Result { name, changed } |
| disable | DisableInput { name* } | Result { name, changed } |
Settings (0)
None. Declare them with behavior.Config.
Telemetry
| Span | behavior.service.<method> |
| Child spans | behavior.object.<method>, behavior.managedfile.<method>, exec systemctl, 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 | name (get, create, update, delete, start, stop, restart, enable, disable) |
Method list
| Name | list |
| Verb | read |
| Description | List the services of the host |
| Detail | Lists each service that systemd has loaded, with its state, whether it starts at boot and its description, through gohai. A Mac has no systemd, and reports skipped. |
| HTTP | GET |
| Route | /api/node/{hostname}/service |
| Permission | service:read |
| Command | osapi client node service list |
| Input type | ListInput |
| Output type | []Entry |
Input (0)
None. The method takes no input; its command needs only --target.
Output (4)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service, without .service |
| state | string | What systemd says it does now, such as running, exited or dead |
| enabled | boolean | Whether it starts at boot: the state of its unit file |
| description | string | The Description= of its unit |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A host with two services | (none) | [description=OpenBSD Secure Shell server, enabled=true, name=ssh, state=running] [description=Example app, enabled=false, name=osapi-app, state=dead] |
Method get
| Name | get |
| Verb | read |
| Description | Get one service |
| Detail | Reads one service from the same list, by its name with .service or without it. A service that systemd has not loaded is not found. |
| HTTP | GET |
| Route | /api/node/{hostname}/service/{name} |
| Permission | service:read |
| Command | osapi client node service get |
| Input type | GetInput |
| Output type | Entry |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as nginx, with .service or without it |
Output (4)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service, without .service |
| state | string | What systemd says it does now, such as running, exited or dead |
| enabled | boolean | Whether it starts at boot: the state of its unit file |
| description | string | The Description= of its unit |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A running service | name=ssh | name=ssh, state=running, enabled=true, description=OpenBSD Secure Shell server |
| A name with .service | name=ssh.service | name=ssh, state=running, enabled=true, description=OpenBSD Secure Shell server |
Method create
| Name | create |
| Verb | write |
| Description | Deploy a service |
| Detail | Gets the object from the object store and writes it as the unit file of the service, such as /etc/systemd/system/osapi-app.service for app, then reloads systemd. A unit file at that path that osapi did not write, such as the agent's own osapi-agent.service, is refused. A unit file that already has the content does not change. The service does not start: start and enable are their own actions. |
| HTTP | POST |
| Route | /api/node/{hostname}/service |
| Permission | service:write |
| Command | osapi client node service create |
| Input type | CreateInput |
| Output type | Result |
Input (2)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
| object | string | yes | min length 1, max length 255 | The object that holds the unit file, from osapi client file upload |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Deploy a unit file | name=app, object=app.service | name=app, changed=true |
| A unit file that has the content | name=app, object=app.service | name=app, changed=false |
Method update
| Name | update |
| Verb | write |
| Description | Deploy a new unit file for a service |
| Detail | Writes the object as the unit file of a service that osapi deployed, then reloads systemd when the file changed. A service that osapi did not deploy is not found. |
| HTTP | PUT |
| Route | /api/node/{hostname}/service/{name} |
| Permission | service:write |
| Command | osapi client node service update |
| Input type | UpdateInput |
| Output type | Result |
Input (2)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
| object | string | yes | min length 1, max length 255 | The object that holds the unit file, from osapi client file upload |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| A new unit file | name=app, object=app-v2.service | name=app, changed=true |
Method delete
| Name | delete |
| Verb | write |
| Description | Remove a service that osapi deployed |
| Detail | Stops and disables the service, removes its unit file and reloads systemd. A service with no unit file does not change. |
| HTTP | DELETE |
| Route | /api/node/{hostname}/service/{name} |
| Permission | service:write |
| Command | osapi client node service delete |
| Input type | DeleteInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (3)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Remove a service | name=app | name=app, changed=true |
| A service that osapi did not deploy | name=app | name=app, changed=false |
| A unit file that osapi did not deploy | name=agent | name=agent, changed=false |
Method start
| Name | start |
| Verb | write |
| Description | Start a service that osapi deployed |
| Detail | Starts the service. A service that runs does not change. A service that osapi did not deploy is not found. |
| HTTP | POST |
| Route | /api/node/{hostname}/service/{name}/start |
| Permission | service:write |
| Command | osapi client node service start |
| Input type | StartInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Start the service | name=app | name=app, changed=true |
Method stop
| Name | stop |
| Verb | write |
| Description | Stop a service that osapi deployed |
| Detail | Stops the service. A service that does not run does not change. A service that osapi did not deploy is not found. |
| HTTP | POST |
| Route | /api/node/{hostname}/service/{name}/stop |
| Permission | service:write |
| Command | osapi client node service stop |
| Input type | StopInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Stop the service | name=app | name=app, changed=true |
Method restart
| Name | restart |
| Verb | write |
| Description | Restart a service that osapi deployed |
| Detail | Restarts the service. It always changes the host. A service that osapi did not deploy is not found. |
| HTTP | POST |
| Route | /api/node/{hostname}/service/{name}/restart |
| Permission | service:write |
| Command | osapi client node service restart |
| Input type | RestartInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Restart the service | name=app | name=app, changed=true |
Method enable
| Name | enable |
| Verb | write |
| Description | Make a service that osapi deployed start at boot |
| Detail | Enables the service. A service that is enabled does not change, and nor does a unit with no [Install] section, which systemd calls static: it cannot start at boot. A service that osapi did not deploy is not found. |
| HTTP | POST |
| Route | /api/node/{hostname}/service/{name}/enable |
| Permission | service:write |
| Command | osapi client node service enable |
| Input type | EnableInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Enable the service | name=app | name=app, changed=true |
| A unit with no [Install] section | name=static | name=static, changed=false |
Method disable
| Name | disable |
| Verb | write |
| Description | Make a service that osapi deployed not start at boot |
| Detail | Disables the service. A service that is not enabled does not change. A service that osapi did not deploy is not found. |
| HTTP | POST |
| Route | /api/node/{hostname}/service/{name}/disable |
| Permission | service:write |
| Command | osapi client node service disable |
| Input type | DisableInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| name | string | yes | pattern ^[a-zA-Z0-9_@.-]+$ | The service, such as app for osapi-app.service |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| name | string | The service |
| changed | boolean | Whether the host changed |
Examples (1)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Disable the service | name=app | name=app, changed=true |