1.\" $OpenBSD: hostctl.8,v 1.5 2017/07/21 20:58:07 mikeb Exp $ 2.\" 3.\" Copyright (c) 2016 Reyk Floeter <reyk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 21 2017 $ 18.Dt HOSTCTL 8 19.Os 20.Sh NAME 21.Nm hostctl 22.Nd display or modify contents of the host's key-value store 23.Sh SYNOPSIS 24.Nm 25.Op Fl qt 26.Op Fl f Ar device 27.Op Fl i Ar input 28.Op Fl o Ar output 29.Ar key 30.Op Ar value 31.Sh DESCRIPTION 32The 33.Nm 34program provides a generic interface for accessing key-value stores on 35the system's host. 36It is primarily used for an abstracted way to exchange information 37with hypervisors that are supported by the 38.Xr pvbus 4 39subsystem. 40When given the name of a specific 41.Ar key , 42.Nm 43will display the value or list the key names of the subtree. 44If the key is followed by a 45.Ar value , 46.Nm 47will write the new key-value pair to the key-value store. 48.Pp 49The options are as follows: 50.Bl -tag -width Ds 51.It Fl f Ar device 52Use 53.Ar device 54instead of the default 55.Pa /dev/pvbus0 . 56.It Fl i Ar input 57Read the new value for the specified 58.Ar key 59from the 60.Ar input 61file. 62.It Fl o Ar output 63Save the returned value in the 64.Ar output 65file. 66.It Fl q 67Don't ask for confirmation of any default options. 68.It Fl t 69Print the type of the underlying driver. 70.El 71.Pp 72Multiple hypervisor interfaces and key-value stores can be simultaneously 73available and reached through different device nodes. 74.Sh FILES 75.Bl -tag -width "/dev/pvbusX" -compact 76.It /dev/pvbus Ns Ar u 77.Xr pvbus 4 78device unit 79.Ar u 80file. 81.El 82.Sh EXAMPLES 83The 84.Xr vmt 4 85driver provides access to the 86.Dq guestinfo 87information that is available in VMware virtual machines: 88.Bd -literal -offset indent 89# hostctl guestinfo.hostname 90vm-111.example.com 91# hostctl guestinfo.ip 192.168.100.111 92.Ed 93.Pp 94The 95.Xr xen 4 96driver provides access to the XenStore that is available in Xen 97virtual machines. 98The 99.Xr pvbus 4 100layer abstracts it as a simple key-value interface: 101.Bd -literal -offset indent 102# hostctl device/vif/0/mac 103fe:e1:ba:d0:27:0f 104# hostctl device/vif/0/description "My interface" 105.Ed 106.Pp 107The XenStore is a virtual filesystem that also provides directories. 108The directory name can be specified as a key to return the contents, 109other keys, of the directory: 110.Bd -literal -offset indent 111# hostctl device 112vfb 113vbd 114vif 115console 116.Ed 117.Pp 118Access to the Hyper-V Key-Value Pair exchange interface is provided by the 119.Xr hyperv 4 120driver. 121The 122.Xr pvbus 4 123layer abstracts access to several pre-defined key pools: 124.Em Auto , 125.Em Guest , 126.Em External 127and 128.Em Guest/Parameters . 129Available keys can be listed and set: 130.Bd -literal -offset indent 131# hostctl Auto/ 132FullyQualifiedDomainName 133IntegrationServicesVersion 134NetworkAddressIPv4 135NetworkAddressIPv6 136OSBuildNumber 137OSName 138OSMajorVersion 139OSMinorVersion 140OSVersion 141ProcessorArchitecture 142# hostctl Auto/FullyQualifiedDomainName `hostname` 143.Ed 144.Sh SEE ALSO 145.Xr pvbus 4 146.Sh HISTORY 147The 148.Nm 149program first appeared in 150.Ox 5.9 . 151.Sh AUTHORS 152The 153.Nm 154program was written by 155.An Reyk Floeter Aq Mt reyk@openbsd.org . 156