diff --git a/README.md b/README.md index 7b1a0e9..05b955b 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,86 @@ -# Linux VM Contextualization +# OpenNebula Linux VM Contextualization -These are the source of the contextualization packages used by VM to be -configured with the information generated by OpenNebula. This add-on is -compatible with OpenNebula >= 4.6. +## Description -## Get packages +This addon provides contextualization packages for the Linux (and, other +Unix-like) guest virtual machines running in the OpenNebula cloud. Based +on the provided contextualization parameters, the packages prepare the +networking in the running guest virt. machine, configure SSH keys, set +passwords, run custom start scripts, and many others. + +## Download Latest versions can be downloaded from the [release page](https://github.com/OpenNebula/addon-context-linux/releases). +Check the supported OpenNebula versions for each release. + +Documentation on packages installation and guest contextualization can +be found in the latest stable +[OpenNebula Operation Guide](http://docs.opennebula.org/stable/operation/vm_setup/context_overview.html). +For beta releases, refer to the latest +[development documentation](http://docs.opennebula.org/devel/operation/vm_setup/context_overview.html). ## Tested platforms -| Platform | Versions | -|-------------------------------------|----------------------------------------| -| CentOS | 6, 7 | -| Red Hat Enterprise Linux | 7 | -| Fedora | 28, 29 | -| openSUSE | 42.3, 15 | -| SUSE Linux Enterprise Server (SLES) | 12 SP3 | -| Debian | 8, 9, 10 | -| Devuan | 1, 2 | -| Ubuntu | 14.04, 16.04, 18.04, 18.10 | -| Alpine Linux | 3.6, 3.7, 3.8 | -| Amazon Linux | 2 | -| FreeBSD | 11.2, 12.0 | +List of tested platforms only: + +| Platform | Versions | +|---------------------------------|----------------------------------------| +| Amazon Linux | 2 | +| CentOS | 6, 7 | +| Red Hat Enterprise Linux | 7 | +| Fedora | 28, 29 | +| openSUSE | 42.3, 15 | +| SUSE Linux Enterprise Server | 12 SP3 | +| Debian | 8, 9, 10 | +| Devuan | 1, 2 | +| Ubuntu | 14.04, 16.04, 18.04, 18.10 | +| Alpine Linux | 3.6, 3.7, 3.8 | +| FreeBSD | 11.2, 12.0 | + +(the packages might work on other versions or flavours, but those aren't tested) + +## Build own package + +Packages for each release for supported guests are available in the +[release page](https://github.com/OpenNebula/addon-context-linux/releases). +Also, any version can be built by the scripts provided in this repository. + +### Requirements + +* **Linux host** +* **Ruby** >= 1.9 +* gem **fpm** >= 1.10.0 +* **dpkg utils** for deb package creation +* **rpm utils** for rpm package creation + +### Steps + +The script `generate.sh` is able to create all package types and can be +configured to include more files in the package or change some of +its parameters. Package type and content are configured by the env. variable +`TARGET`, the corresponding target must be defined in `target.sh`. Target +describes the package format, name, dependencies, and files. Files are +selected by the tags. Set of required tags is defined for the target +(in `targets.sh`), each file has a list of corresponding tags right in its +filename (divided by the regular name by 2 hashes `##`, dot-separated). + +Package name or version can be overridden by env. variables `NAME` and `VERSION`. + +Examples: + +``` +$ TARGET=deb ./generate.sh +$ TARGET=el7 NAME=my-one-context ./generate.sh +$ TARGET=alpine ./generate.sh +$ TARGET=freebsd VERSION=5.7.85 ./generate.sh +``` + +NOTE: The generator must be executed from the same directory it resides. + +Check `generate.sh` for general package metadata and `targets.sh` for the list +of targets and their metadata. Most of the parameters can be overriden by +the appropriate environment variable. ## Development @@ -62,101 +119,16 @@ divided into following 2 parts: All other scripts, which are not prefixed with `loc-` or `net-`, are executed as a first during the post-networking contextualization stage. -## Build own package - -Package contains following parts: - -* main control scripts (`/usr/sbin/one-context*`) -* contextualization scripts (`/etc/one-context.d/*`) -* init scripts to start the contextualization -* OneGate scripts (`/usr/bin/one-gate*`) -* udev rules to trigger reconfiguration on NIC hotplug - -Other actions include: +## License -* delete persistent cd and net rules from /etc/udev/rules.d -* delete network configuration files - -### Requirements - - * Ruby >= 1.8.7 - * gem fpm >= 1.8.1 - * dpkg utils for deb package creation - * rpm utils for rpm package creation - -On Ubuntu/Debian you can install the package `rpm` and you will be able -to generate both rpm and deb packages. - -### Steps - -The script `generate.sh` is able to create both **deb** and **rpm** packages -and can be configured to include more files in the package or change some of -its parameters. Package type and content are configured by the env. variable -`TARGET`, the corresponding target must be defined in `target.sh`. Target -describes the package format, name, dependencies, and files. Files are -selected by the tags. Set of required tags is defined for the target -(in `targets.sh`), each file has a list of corresponding tags right in its -filename (divided by the regular name by 2 hashes `##`, dot-separated). - -On start it creates a temporary directory and copies there: - - * All files tagged with no, some (but only from TARGET set) or all tags. - * Any file or directory from the arguments. - -The default parameters to create a package are as follows: - -``` -VERSION=1.0.1 -RELEASE=1 -MAINTAINER="OpenNebula Systems " -LICENSE="Apache 2.0" -VENDOR="OpenNebula Systems" -DESCRIPTION=" -This package prepares a VM image for OpenNebula: - * Disables udev net and cd persistent rules - * Deletes udev net and cd persistent rules - * Unconfigures the network - * Adds OpenNebula contextualization scripts to startup - -To get support use the OpenNebula mailing list: - http://OpenNebula.org -" -URL=http://opennebula.org -``` - -A target contains following parameters, e.g. **el7** target: - -``` -NAME=one-context -RELSUFFIX=.el7 -TYPE=rpm -TAGS="rpm systemd one" -DEPENDS="util-linux bind-utils cloud-utils-growpart ruby rubygem-json" -REPLACES="cloud-init" -POSTIN=postinstall.one -PREUN=preuninstall.one -``` - -You can change any parameter setting an environment variable with the same name. -For example, to generate an **el7 rpm** package with a different package name: - -``` -$ TARGET=el7 NAME=my-one-context ./generate.sh -``` - -You can also include new files. This is handy to include new scripts executed -to contextualize an image. For example, we can have a script that installs -a user ssh key. We will create the file hierarchy that will go inside -the package in a directory: - -``` -$ mkdir -p ssh/etc/one-context.d -$ cp ssh/etc/one-context.d/loc-01-ssh-key -$ TARGET=el7 ./generate.sh ssh/etc -``` - -NOTE: The generator must be executed from the same directory it resides. +Copyright 2002-2019, OpenNebula Project, OpenNebula Systems (formerly C12G Labs) -## Authors +Licensed under the Apache License, Version 2.0 (the "License"); you may +not use this file except in compliance with the License. You may obtain +a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 -* Leader: Javier Fontan (jfontan@opennebula.org) +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License.