meta-data.8

.\"	$OpenBSD: mdoc.template,v 1.15 2014/03/31 00:09:54 dlg Exp $
.\"
.\" Copyright (c) 2017 Reyk Floeter <reyk@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt META-DATA 8
.Os
.Sh NAME
.Nm meta-data
.Nd meta-data server for OpenBSD's virtual machine daemon
.Sh SYNOPSIS
.Nm meta-data
.Op Fl 23
.Op Fl u Ar user
.Op Fl l Ar lease-file
.Op Ar bridge
.Sh DESCRIPTION
The
.Nm
FastCGI program provides a cloud-init datasource for
.Ox Ap s
.Xr vmd 8
that is compatible with Apache CloudStack
and partially compatible with Amazon EC2.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 2
Run in layer
.Cm 2
mode.
.Nm
will find the guest VM by its MAC address in the DHCP
.Ar lease-file
and the
.Ar bridge
cache.
This is the default if layer
.Cm 3
mode is not specified.
The default bridge name is
.Dq bridge0 .
.It Fl 3
Run in layer
.Cm 3
mode.
.Nm
will find the guest VM by its IPv4 address in the ARP table.
The layer
.Cm 2
and
.Cm 3
modes can be combined.
.It Fl u Ar user
Change the
.Ar user
name.
The default is
.Dq _meta-data .
.It Fl l Ar lease-file
Change the
.Ar lease-file .
The default is
.Pa /var/db/dhcpd.leases .
.El
.Pp
Use the following steps to run
.Nm :
.Bl -enum
.It
Create the
.Pa meta-data
directory and add the
.Dq _meta-data
user:
.Bd -literal -offset indent
# mkdir -p /home/vm/meta-data
# groupadd -g 787 _meta-data
# useradd -g 787 -u 787 -k /var/empty -d /home/vm/meta-data \e
	-s /sbin/nologin -c "meta-data user" _meta-data
.Ed
.It
Use the
.Xr kfcgi 8
FastCGI server to run
.Nm .
Start it as root, with chroot disabled, and
.Nm
will drop privileges by itself.
The
.Nm
socket has to be owned by the "www" user of the web server.
.Bd -literal -offset indent
# kfcgi -r -n 2 -u www -p / -- /usr/local/libexec/meta-data
.Ed
.It
Configure and start
.Xr httpd 8
to handle
.Nm
requests:
.Bd -literal -offset indent
server "meta-data" {
	listen on 169.254.169.254 port 80
	fastcgi socket "/run/httpd.sock"
	root { "/", strip 1 }
}
.Ed
.El
.Sh ATTRIBUTES
.Nm
serves a number of attributes, so-called meta-data items and optional
user-data, that are specific to the requesting VM.
The following attributes are supported:
.Bl -tag -width Ds
.It Cm meta-data/availability-zone
This option is provided for compatibility.
It includes the name of the
.Ar bridge
interface.
.It Cm meta-data/instance-id
The VM identifier in the format
.Ic vm Ns Ar ID ,
e.g.\&
.Ar vm1 .
.It Cm meta-data/local-hostname
The hostname of the guest VM,
based on the VM name that was specified in
.Xr vm.conf 5
or by the
.Xr vmctl 8
.Ic start
command.
.It Cm meta-data/local-ipv4
The IPv4 address of the guest VM.
It is identical to the verified guest IP address of the HTTP request.
.It Cm meta-data/public-hostname
This option is provided for compatibility.
It includes the hostname of the
.Xr vmd 8
host where
.Nm
is running.
.It Cm meta-data/public-ipv4
This option is provided for compatibility.
It currently includes the fixed string
.Qq 127.0.0.1 .
.It Cm meta-data/public-keys/0/openssh-key
The SSH public key that is included in the
.Pa openssh-key
file in the VM's configuration directory.
See the
.Sx FILES
section below.
.Nm
returns an
.Dq HTTP 404 Not Found
error if the file does not exist.
.It Cm meta-data/service-offering
This option is provided for compatibility.
It includes the fixed string
.Qq OpenBSD .
.It Cm meta-data/username
Returns the contents of the
.Pa username
file in the VM's configuration directory,
or
.Dq root
if it does not exist.
This item is not available in other meta-data implementations.
.It Cm user-data
Returns the contents of the
.Pa user-data
file in the VM's configuration directory,
or an
.Dq HTTP 404 Not Found
if it does not exist.
The user-data file typically includes a configuration file or shell
script of a type that is indicated by the
.Dq shebang
in the first line, for example
.Qq #!/bin/sh
or
.Qq #cloud-config .
.El
.Sh FILES
.Bl -tag -width "/home/vm/meta-data/openbsd.vmX" -compact
.It Pa /home/vm/meta-data/openbsd.vm
Directory containing meta-data for the virtual machine
.Dq openbsd.vm .
.It Pa openssh-key
The SSH public key in the VM's meta-data directory.
.It Pa user-data
"user-data" file in the VM's meta-data directory.
.It Pa username
The login username (this is an extension).
.El
.\" .Sh EXAMPLES
.Sh SEE ALSO
.Xr kcgi 8 ,
.Xr kfcgi 8 ,
.Xr vmd 8
.\" .Sh STANDARDS
.Rs
.%U http://docs.cloudstack.apache.org/projects/cloudstack-administration/en/latest/virtual_machines.html#user-data-and-meta-data
.%T User-Data and Meta-Data
.Re
.\" .Sh HISTORY
.Sh AUTHORS
.An Reyk Floeter Aq Mt reyk@openbsd.org
.\" .Sh CAVEATS
.\" .Sh BUGS