micro-config-drive/docs/ucd.1

'\" t
.TH "MICRO-CONFIG-DRIVE" "1" "" "ucd 1" "ucd"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ucd \- Configures a cloud instance using config-drive data

.SH "SYNOPSIS"
.HP \w'\fBucd\fR\ 'u
\fBucd\fR [OPTIONS...]

.SH "DESCRIPTION"
.PP
\fBucd\fR
runs at boot time with the purpose of configuring a cloud instance
for use of the end user.
.PP
ucd can perform any of the following (optional) tasks:
 * create a default account with sudo privileges
 * lock root and default account, the only way to login is using ssh keys (security feature)
 * maintain the cloud instance in a right state (resize/fix partitions and filesystem)
 * get and process userdata and metadata from an attached config-drive block device

Userdata formats supported:
 * \fIcloud-config\fR: begins with \fB#cloud-config\fR and is used to execute certain tasks in a human friendly format
 * \fIshell-script\fR: begins wiht \fB#!\fR and is used to execute a shell script

Metadata formats supported:
 * \fIopenstack\fR

.SH "OPENSTACK DATASOURCES"
Datasources are used to retrive instance-specific data in order to configure a new cloud instance.
Openstack attaches two datasources to the cloud instance when it boots and these are listed bellow. 
 * \fIconfig-drive\fR: is a disk formatted with vfat or iso9660 and have a label of config-2
 * \fImetadata service\fR: instances can access to it at http://169.254.169.254 \fB[NOT SUPPORTED]\fR

more information about openstack datasources can be found in:
\%http://docs.openstack.org/user-guide/cli_config_drive.html
\%http://docs.openstack.org/admin-guide/compute-networking-nova.html#metadata-service
.RE

.SH "WORKFLOW"
    \fB|\fR Parse options
    \fB|\fR Init openstack datasource
    \fB|->\fR if config-drive is found then define it as datasource otherwise exit
    \fB|\fR Start openstack datasource
    \fB|->\fR Get userdata and metadata from datasource
    \fB|\fR Run async tasks
    \fB|->\fR resize disk
    \fB|->\fR resize filesystem
    \fB|\fR If a datasource was found
    \fB|->\fR if VM first boot was detected
    \fB|   |->\fR Run async tasks
    \fB|   |   |->\fR lock root account
    \fB|   |   |->\fR Create sudoers file for default user account
    \fB|   |->\fR Create default user account
    \fB|->\fR Process openstack metadata
    \fB|->\fR Process openstack userdata
    \fB|\fR Join async tasks
    \fB|\fR Finish openstack datasource (free resources)
.RE

.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Prints a help message\&.
.RE
.PP
\fB\-u\fR FILE, \fB\-\-user\-data\-file\fR FILE
.RS 4
Path to a cloud-config user data file\&. If omitted, \fBucd\fR will
attempt to fetch user-data from the openstack link-local connected data
service URL.
.RE
.PP
\fB\-\-openstack\-metadata\-file\fR FILE
.RS 4
Path to an openstack metadata file.
 more information: \%http://docs.openstack.org/user-guide/cli_config_drive.html#openstack-metadata-format
.RE
.PP
\fB\-\-openstack\-config\-drive\fR PATH
.RS 4
Path to openstack config drive (iso9660 or vfat filesystem),
it will be used to process metadata and userdata.
 more information:
\%http://docs.openstack.org/user-guide/cli_config_drive.html#configuration-drive-contents
.RE
.PP
\fB\-\-user\-data\fR
.RS 4
Get and process user data from data sources.
.RE
.PP
\fB\-\-user\-data\-once\fR
.RS 4
Only on first boot get and process user data from data sources.
Note this option is ignored if \fB\-\-user\-data\fR is enabled.
.RE
.PP
\fB\-\-metadata\fR
.RS 4
Get and process metadata from data sources.
.RE
.PP
\fB\-\-fix\-disk\fR
.RS 4
Fix disk and filesystem if it is needed.
.RE
.PP
\fB\-v\fR, \fB\-\-version\fR
.RS 4
Prints version information\&.
.RE
.PP
\fB\-\-first\-boot\-setup\fR
.RS 4
Setup the instance in its first boot.
When first boot of the instance is detected, \fBucd\fR will perform
next tasks:
 * create a default user account
 * create sudoers file for default user account
 * lock root account
.RE

.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.

.SH "COPYRIGHT"
.PP
Copyright 2015 Intel Corporation\&. License: Creative Commons
Attribution\-ShareAlike 3.0 Unported\s-2\u[1]\d\s+2\&.

.SH "SEE ALSO"
.PP
This project is a limited-functionality implementation of the ucd
specification. The full documentation of the generic implementation is
available online and can be referenced here:
.RS 4
\fBhttps://cloudinit.readthedocs.org/en/latest/\fR
.RE
.PP
The cloud-config format that \fBucd\fR(1) supports is documented
in \fBcloud-config\fR(5). This lists the options that are supported,
their structure and function.

.SH "NOTES"
.IP " 1." 4
Creative Commons Attribution\-ShareAlike 3.0 Unported
.RS 4
\%http://creativecommons.org/licenses/by-sa/3.0/
.RE