Skip to main content

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​

Nameservice
DescriptionThe systemd services of the host
Placementnode
Internalno
APIyes
CLIyes
Nextno
Platformsdebian, linux
Sudonone
Runssystemctl
Writes/etc/systemd/system/osapi-*.service
Keeps stateno
Usesobject, managedfile
Used bynone

Methods (10)​

NAMEVERBHTTPROUTEPERMISSIONDESCRIPTION
listreadGET/api/node/{hostname}/serviceservice:readList the services of the host
getreadGET/api/node/{hostname}/service/{name}service:readGet one service
createwritePOST/api/node/{hostname}/serviceservice:writeDeploy a service
updatewritePUT/api/node/{hostname}/service/{name}service:writeDeploy a new unit file for a service
deletewriteDELETE/api/node/{hostname}/service/{name}service:writeRemove a service that osapi deployed
startwritePOST/api/node/{hostname}/service/{name}/startservice:writeStart a service that osapi deployed
stopwritePOST/api/node/{hostname}/service/{name}/stopservice:writeStop a service that osapi deployed
restartwritePOST/api/node/{hostname}/service/{name}/restartservice:writeRestart a service that osapi deployed
enablewritePOST/api/node/{hostname}/service/{name}/enableservice:writeMake a service that osapi deployed start at boot
disablewritePOST/api/node/{hostname}/service/{name}/disableservice:writeMake a service that osapi deployed not start at boot

Types (10)​

NAMEINPUTOUTPUT
listListInput[]Entry { name, state, enabled, description }
getGetInput { name* }Entry { name, state, enabled, description }
createCreateInput { name*, object* }Result { name, changed }
updateUpdateInput { name*, object* }Result { name, changed }
deleteDeleteInput { name* }Result { name, changed }
startStartInput { name* }Result { name, changed }
stopStopInput { name* }Result { name, changed }
restartRestartInput { name* }Result { name, changed }
enableEnableInput { name* }Result { name, changed }
disableDisableInput { name* }Result { name, changed }

Settings (0)​

None. Declare them with behavior.Config.

Telemetry​

Spanbehavior.service.<method>
Child spansbehavior.object.<method>, behavior.managedfile.<method>, exec systemctl, exec chown, exec stat, file.write, file.remove, file.chmod, kv.get, kv.put
Metricsosapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total
Attributesosapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed
Recorded inputsname (get, create, update, delete, start, stop, restart, enable, disable)

Method list​

Namelist
Verbread
DescriptionList the services of the host
DetailLists 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.
HTTPGET
Route/api/node/{hostname}/service
Permissionservice:read
Commandosapi client node service list
Input typeListInput
Output type[]Entry

Input (0)​

None. The method takes no input; its command needs only --target.

Output (4)​

FIELDTYPEDESCRIPTION
namestringThe service, without .service
statestringWhat systemd says it does now, such as running, exited or dead
enabledbooleanWhether it starts at boot: the state of its unit file
descriptionstringThe Description= of its unit

Examples (1)​

EXAMPLEINPUTOUTPUT
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​

Nameget
Verbread
DescriptionGet one service
DetailReads one service from the same list, by its name with .service or without it. A service that systemd has not loaded is not found.
HTTPGET
Route/api/node/{hostname}/service/{name}
Permissionservice:read
Commandosapi client node service get
Input typeGetInput
Output typeEntry

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as nginx, with .service or without it

Output (4)​

FIELDTYPEDESCRIPTION
namestringThe service, without .service
statestringWhat systemd says it does now, such as running, exited or dead
enabledbooleanWhether it starts at boot: the state of its unit file
descriptionstringThe Description= of its unit

Examples (2)​

EXAMPLEINPUTOUTPUT
A running servicename=sshname=ssh, state=running, enabled=true, description=OpenBSD Secure Shell server
A name with .servicename=ssh.servicename=ssh, state=running, enabled=true, description=OpenBSD Secure Shell server

Method create​

Namecreate
Verbwrite
DescriptionDeploy a service
DetailGets 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.
HTTPPOST
Route/api/node/{hostname}/service
Permissionservice:write
Commandosapi client node service create
Input typeCreateInput
Output typeResult

Input (2)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service
objectstringyesmin length 1, max length 255The object that holds the unit file, from osapi client file upload

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
Deploy a unit filename=app, object=app.servicename=app, changed=true
A unit file that has the contentname=app, object=app.servicename=app, changed=false

Method update​

Nameupdate
Verbwrite
DescriptionDeploy a new unit file for a service
DetailWrites 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.
HTTPPUT
Route/api/node/{hostname}/service/{name}
Permissionservice:write
Commandosapi client node service update
Input typeUpdateInput
Output typeResult

Input (2)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service
objectstringyesmin length 1, max length 255The object that holds the unit file, from osapi client file upload

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
A new unit filename=app, object=app-v2.servicename=app, changed=true

Method delete​

Namedelete
Verbwrite
DescriptionRemove a service that osapi deployed
DetailStops and disables the service, removes its unit file and reloads systemd. A service with no unit file does not change.
HTTPDELETE
Route/api/node/{hostname}/service/{name}
Permissionservice:write
Commandosapi client node service delete
Input typeDeleteInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (3)​

EXAMPLEINPUTOUTPUT
Remove a servicename=appname=app, changed=true
A service that osapi did not deployname=appname=app, changed=false
A unit file that osapi did not deployname=agentname=agent, changed=false

Method start​

Namestart
Verbwrite
DescriptionStart a service that osapi deployed
DetailStarts the service. A service that runs does not change. A service that osapi did not deploy is not found.
HTTPPOST
Route/api/node/{hostname}/service/{name}/start
Permissionservice:write
Commandosapi client node service start
Input typeStartInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
Start the servicename=appname=app, changed=true

Method stop​

Namestop
Verbwrite
DescriptionStop a service that osapi deployed
DetailStops the service. A service that does not run does not change. A service that osapi did not deploy is not found.
HTTPPOST
Route/api/node/{hostname}/service/{name}/stop
Permissionservice:write
Commandosapi client node service stop
Input typeStopInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
Stop the servicename=appname=app, changed=true

Method restart​

Namerestart
Verbwrite
DescriptionRestart a service that osapi deployed
DetailRestarts the service. It always changes the host. A service that osapi did not deploy is not found.
HTTPPOST
Route/api/node/{hostname}/service/{name}/restart
Permissionservice:write
Commandosapi client node service restart
Input typeRestartInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
Restart the servicename=appname=app, changed=true

Method enable​

Nameenable
Verbwrite
DescriptionMake a service that osapi deployed start at boot
DetailEnables 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.
HTTPPOST
Route/api/node/{hostname}/service/{name}/enable
Permissionservice:write
Commandosapi client node service enable
Input typeEnableInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
Enable the servicename=appname=app, changed=true
A unit with no [Install] sectionname=staticname=static, changed=false

Method disable​

Namedisable
Verbwrite
DescriptionMake a service that osapi deployed not start at boot
DetailDisables the service. A service that is not enabled does not change. A service that osapi did not deploy is not found.
HTTPPOST
Route/api/node/{hostname}/service/{name}/disable
Permissionservice:write
Commandosapi client node service disable
Input typeDisableInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyespattern ^[a-zA-Z0-9_@.-]+$The service, such as app for osapi-app.service

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe service
changedbooleanWhether the host changed

Examples (1)​

EXAMPLEINPUTOUTPUT
Disable the servicename=appname=app, changed=true