Skip to main content

Hostname

Get or set the hostname of target hosts. osapi behavior get --name hostname and osapi behavior method get show the same.

Behavior​

Namehostname
DescriptionGet or set the hostname of target hosts
Placementnode
Internalno
APIyes
CLIyes
Nextno
Platformslinux, darwin
Sudonone
Runshostname
Writesnone
Keeps stateno
Usesnone
Used bystatus

Methods (2)​

NAMEVERBHTTPROUTEPERMISSIONDESCRIPTION
getreadGET/api/node/{hostname}/hostnamehostname:readGet the hostname of the host
updatewritePUT/api/node/{hostname}/hostnamehostname:writeSet the hostname of the host

Types (2)​

NAMEINPUTOUTPUT
getGetInputEntry { name }
updateUpdateInput { name* }Result { name, changed }

Settings (0)​

None. Declare them with behavior.Config.

Telemetry​

Spanbehavior.hostname.<method>
Child spansexec hostnamectl, exec hostname
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 (update)

Method get​

Nameget
Verbread
DescriptionGet the hostname of the host
DetailReads the host's name as the hostname command prints it, on Linux and on macOS. It makes no DNS lookup.
HTTPGET
Route/api/node/{hostname}/hostname
Permissionhostname:read
Commandosapi client node hostname get
Input typeGetInput
Output typeEntry

Input (0)​

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

Output (1)​

FIELDTYPEDESCRIPTION
namestringThe hostname of the host

Examples (1)​

EXAMPLEINPUTOUTPUT
A host named web-01(none)name=web-01

Method update​

Nameupdate
Verbwrite
DescriptionSet the hostname of the host
DetailSets the static hostname with hostnamectl set-hostname, which keeps it after a reboot. A host that already has the name does not change and reports changed: false. It runs on the Debian family only, and elsewhere reports skipped. In a container the runtime owns the hostname, so there it also reports skipped.
HTTPPUT
Route/api/node/{hostname}/hostname
Permissionhostname:write
Commandosapi client node hostname update
Input typeUpdateInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
namestringyesformat hostname, max length 253The hostname to set, such as web-01

Output (2)​

FIELDTYPEDESCRIPTION
namestringThe hostname of the host
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
Rename a hostname=web-02name=web-02, changed=true
A host that already has the namename=web-01name=web-01, changed=false