Update upstream source from tag 'upstream/1.0.0+git20201203.e939090'

Update to upstream version '1.0.0+git20201203.e939090'
with Debian dir d1c1f361279ce5e1f9462923fbb9cfe3103faa55

3 files changed, 166 insertions, 85 deletions

diff --git a/README.md b/README.md
index 38691b8..ff2fc49 100644
--- a/README.md
+++ b/README.md
@@ -7,15 +7,20 @@
 
 Application Options:
 
-          --artifactdir=
-      -t, --template-var=   Template variables
-          --debug-shell     Fall into interactive shell on error
-      -s, --shell=          Redefine interactive shell binary (default: bash)
-          --scratchsize=    Size of disk backed scratch space
-      -e, --environ-var=    Environment variables
-      -v, --verbose         Verbose output
-          --print-recipe    Print final recipe
-          --dry-run         Compose final recipe to build but without any real work started
+      -b, --fakemachine-backend=   Fakemachine backend to use (default: auto)
+          --artifactdir=           Directory for packed archives and ostree repositories (default: current directory)
+      -t, --template-var=          Template variables (use -t VARIABLE:VALUE syntax)
+          --debug-shell            Fall into interactive shell on error
+      -s, --shell=                 Redefine interactive shell binary (default: bash) (default: /bin/bash)
+          --scratchsize=           Size of disk backed scratch space
+      -c, --cpus=                  Number of CPUs to use for build VM (default: 2)
+      -m, --memory=                Amount of memory for build VM (default: 2048MB)
+          --show-boot              Show boot/console messages from the fake machine
+      -e, --environ-var=           Environment variables (use -e VARIABLE:VALUE syntax)
+      -v, --verbose                Verbose output
+          --print-recipe           Print final recipe
+          --dry-run                Compose final recipe to build but without any real work started
+          --disable-fakemachine    Do not use fakemachine.
 
 
 ## Description
@@ -146,5 +151,17 @@ fakemachine, there are two known sources of issues:
 
 * In case you are running applications and/or scripts inside fakemachine you may need to check which are the proxy environment variables they use. Different apps are known to use different environment variable names and different case for environment variable names.
 
-## See also
-fakemachine at https://github.com/go-debos/fakemachine
+## Fakemachine Backend
+
+debos (unless running debos with the `--disable-fakemachine` argument) creates
+and spawns a virtual machine using [fakemachine](https://github.com/go-debos/fakemachine)
+and executes the actions defined by the recipe inside the virtual machine. This
+helps ensure recipes are reproducible no matter the host environment.
+
+Fakemachine can use different virtualisation backends to spawn the virtualmachine,
+for more information see the documentation under the [fakemachine repository](https://github.com/go-debos/fakemachine).
+
+By default the backend will automatically be selected based on what is supported
+on the host machine, but this can be overridden using the `--fakemachine-backend`
+option. If no backends are supported, debos reverts to running the recipe on the
+host without creating a fakemachine.
diff --git a/cmd/debos/debos.go b/cmd/debos/debos.go
index a31ef98..0f9d6a1 100644
--- a/cmd/debos/debos.go
+++ b/cmd/debos/debos.go
@@ -59,6 +59,7 @@ func warnLocalhost(variable string, value string) {
 func main() {
 	context := debos.DebosContext { &debos.CommonContext{}, "", "" }
 	var options struct {
+		Backend       string            `short:"b" long:"fakemachine-backend" description:"Fakemachine backend to use" default:"auto"`
 		ArtifactDir   string            `long:"artifactdir" description:"Directory for packed archives and ostree repositories (default: current directory)"`
 		InternalImage string            `long:"internal-image" hidden:"true"`
 		TemplateVars  map[string]string `short:"t" long:"template-var" description:"Template variables (use -t VARIABLE:VALUE syntax)"`
@@ -94,8 +95,10 @@ func main() {
 	}()
 
 	parser := flags.NewParser(&options, flags.Default)
-	args, err := parser.Parse()
+	fakemachineBackends := parser.FindOptionByLongName("fakemachine-backend")
+	fakemachineBackends.Choices = fakemachine.BackendNames()
 
+	args, err := parser.Parse()
 	if err != nil {
 		flagsErr, ok := err.(*flags.Error)
 		if ok && flagsErr.Type == flags.ErrHelp {
@@ -112,6 +115,12 @@ func main() {
 		return
 	}
 
+	if options.DisableFakeMachine && options.Backend != "auto" {
+		log.Println("--disable-fakemachine and --fakemachine-backend are mutually exclusive")
+		exitcode = 1
+		return
+	}
+
 	// Set interactive shell binary only if '--debug-shell' options passed
 	if options.DebugShell {
 		context.DebugShell = options.Shell
@@ -140,12 +149,34 @@ func main() {
 		return
 	}
 
-	/* If fakemachine is supported the outer fake machine will never use the
+	/* If fakemachine is used the outer fake machine will never use the
 	 * scratchdir, so just set it to /scratch as a dummy to prevent the
-	 * outer debos creating a temporary direction */
-	if !options.DisableFakeMachine && (fakemachine.InMachine() || fakemachine.Supported()) {
-		context.Scratchdir = "/scratch"
+	 * outer debos creating a temporary directory */
+	context.Scratchdir = "/scratch"
+
+	var runInFakeMachine = true
+	var m *fakemachine.Machine
+	if options.DisableFakeMachine || fakemachine.InMachine() {
+		runInFakeMachine = false
 	} else {
+		// attempt to create a fakemachine
+		m, err = fakemachine.NewMachineWithBackend(options.Backend)
+		if err != nil {
+			log.Printf("error creating fakemachine: %v", err)
+
+			/* fallback to running on the host unless the user has chosen
+			 * a specific backend */
+			if options.Backend == "auto" {
+				runInFakeMachine = false
+			} else {
+				exitcode = 1
+				return
+			}
+		}
+	}
+
+	// if running on the host create a scratchdir
+	if !runInFakeMachine && !fakemachine.InMachine() {
 		log.Printf("fakemachine not supported, running on the host!")
 		cwd, _ := os.Getwd()
 		context.Scratchdir, err = ioutil.TempDir(cwd, ".debos-")
@@ -212,8 +243,7 @@ func main() {
 		return
 	}
 
-	if !options.DisableFakeMachine && !fakemachine.InMachine() && fakemachine.Supported() {
-		m := fakemachine.NewMachine()
+	if runInFakeMachine {
 		var args []string
 
 		if options.Memory == "" {
diff --git a/doc/man/debos.1 b/doc/man/debos.1
index 44148a0..2592d60 100644
--- a/doc/man/debos.1
+++ b/doc/man/debos.1
@@ -1,46 +1,50 @@
-.\" Automatically generated by Pandoc 2.2.1
+.\" Automatically generated by Pandoc 2.9.2.1
 .\"
 .TH "debos" "1" "" "" ""
 .hy
 .SH NAME
+.PP
+debos - Debian OS images builder
+.SH SYNOPSIS
 .IP
 .nf
 \f[C]
-debos\ \-\ \ Debian\ OS\ images\ builder
-\f[]
-.fi
-.SH SYPNOSIS
-.IP
-.nf
-\f[C]
-debos\ [options]\ <recipe\ file\ in\ YAML>
-debos\ [\-\-help]
-\f[]
+debos [options] <recipe file in YAML>
+debos [--help]
+\f[R]
 .fi
 .PP
 Application Options:
 .IP
 .nf
 \f[C]
-\ \ \ \ \ \ \-\-artifactdir=
-\ \ \-t,\ \-\-template\-var=\ \ \ Template\ variables
-\ \ \ \ \ \ \-\-debug\-shell\ \ \ \ \ Fall\ into\ interactive\ shell\ on\ error
-\ \ \-s,\ \-\-shell=\ \ \ \ \ \ \ \ \ \ Redefine\ interactive\ shell\ binary\ (default:\ bash)
-\ \ \ \ \ \ \-\-scratchsize=\ \ \ \ Size\ of\ disk\ backed\ scratch\ space
-\ \ \-e,\ \-\-environ\-var=\ \ \ \ Environment\ variables
-\f[]
+  -b, --fakemachine-backend=   Fakemachine backend to use (default: auto)
+      --artifactdir=           Directory for packed archives and ostree repositories (default: current directory)
+  -t, --template-var=          Template variables (use -t VARIABLE:VALUE syntax)
+      --debug-shell            Fall into interactive shell on error
+  -s, --shell=                 Redefine interactive shell binary (default: bash) (default: /bin/bash)
+      --scratchsize=           Size of disk backed scratch space
+  -c, --cpus=                  Number of CPUs to use for build VM (default: 2)
+  -m, --memory=                Amount of memory for build VM (default: 2048MB)
+      --show-boot              Show boot/console messages from the fake machine
+  -e, --environ-var=           Environment variables (use -e VARIABLE:VALUE syntax)
+  -v, --verbose                Verbose output
+      --print-recipe           Print final recipe
+      --dry-run                Compose final recipe to build but without any real work started
+      --disable-fakemachine    Do not use fakemachine.
+\f[R]
 .fi
 .SH DESCRIPTION
 .PP
-debos is a tool to make the creation of various Debian\-based OS images
+debos is a tool to make the creation of various Debian-based OS images
 simpler.
-While most other tools focus on specific use\-cases, debos is more meant
-as a tool\-chain to make common actions trivial while providing enough
+While most other tools focus on specific use-cases, debos is more meant
+as a tool-chain to make common actions trivial while providing enough
 rope to do whatever tweaking that might be required behind the scene.
 .PP
 debos expects a YAML file as input and will run the actions listed in
 the file sequentially.
-These actions should be self\-contained and independent of each other.
+These actions should be self-contained and independent of each other.
 .PP
 Some of the actions provided by debos to customize and produce images
 are:
@@ -51,14 +55,14 @@ debootstrap: construct the target rootfs with debootstrap
 .IP \[bu] 2
 download: download a single file from the internet
 .IP \[bu] 2
-filesystem\-deploy: deploy a root filesystem to an image previously
+filesystem-deploy: deploy a root filesystem to an image previously
 created
 .IP \[bu] 2
-image\-partition: create an image file, make partitions and format them
+image-partition: create an image file, make partitions and format them
 .IP \[bu] 2
-ostree\-commit: create an OSTree commit from rootfs
+ostree-commit: create an OSTree commit from rootfs
 .IP \[bu] 2
-ostree\-deploy: deploy an OSTree branch to the image
+ostree-deploy: deploy an OSTree branch to the image
 .IP \[bu] 2
 overlay: do a recursive copy of directories or files to the target
 filesystem
@@ -67,22 +71,37 @@ pack: create a tarball with the target filesystem
 .IP \[bu] 2
 raw: directly write a file to the output image at a given offset
 .IP \[bu] 2
+recipe: includes the recipe actions at the given path
+.IP \[bu] 2
 run: allows to run a command or script in the filesystem or in the host
 .IP \[bu] 2
 unpack: unpack files from archive in the filesystem
 .PP
 A full syntax description of all the debos actions can be found at:
-https://godoc.org/github.com/go\-debos/debos/actions
+https://godoc.org/github.com/go-debos/debos/actions
+.SH INSTALLATION (DOCKER CONTAINER)
+.PP
+Official debos container is available:
+.IP
+.nf
+\f[C]
+docker pull godebos/debos
+\f[R]
+.fi
+.PP
+See
+docker/README.md (https://github.com/go-debos/debos/blob/master/docker/README.md)
+for usage.
 .SH INSTALLATION (UNDER DEBIAN)
 .IP
 .nf
 \f[C]
-sudo\ apt\ install\ golang\ git\ libglib2.0\-dev\ libostree\-dev\ qemu\-system\-x86\ \\
-\ \ \ \ \ qemu\-user\-static\ debootstrap\ systemd\-container
-export\ GOPATH=/opt/src/gocode\ #\ or\ whatever\ suites\ your\ needs
-go\ get\ \-u\ github.com/go\-debos/debos/cmd/debos
-/opt/src/gocode/bin/debos\ \-\-help
-\f[]
+sudo apt install golang git libglib2.0-dev libostree-dev qemu-system-x86 \[rs]
+     qemu-user-static debootstrap systemd-container
+export GOPATH=/opt/src/gocode # or whatever suites your needs
+go get -u github.com/go-debos/debos/cmd/debos
+/opt/src/gocode/bin/debos --help
+\f[R]
 .fi
 .SH SIMPLE EXAMPLE
 .PP
@@ -92,38 +111,38 @@ finally make a tarball.
 .IP
 .nf
 \f[C]
-{{\-\ $image\ :=\ or\ .image\ "debian.tgz"\ \-}}
+{{- $image := or .image \[dq]debian.tgz\[dq] -}}
 
-architecture:\ arm64
+architecture: arm64
 
 actions:
-\ \ \-\ action:\ debootstrap
-\ \ \ \ suite:\ "buster"
-\ \ \ \ components:
-\ \ \ \ \ \ \-\ main
-\ \ \ \ \ \ \-\ non\-free
-\ \ \ \ mirror:\ https://deb.debian.org/debian
-\ \ \ \ variant:\ minbase
+  - action: debootstrap
+    suite: \[dq]buster\[dq]
+    components:
+      - main
+      - non-free
+    mirror: https://deb.debian.org/debian
+    variant: minbase
 
-\ \ \-\ action:\ apt
-\ \ \ \ packages:\ [\ sudo,\ openssh\-server,\ adduser,\ systemd\-sysv,\ firmware\-linux\ ]
+  - action: apt
+    packages: [ sudo, openssh-server, adduser, systemd-sysv, firmware-linux ]
 
-\ \ \-\ action:\ run
-\ \ \ \ chroot:\ true
-\ \ \ \ command:\ echo\ debian\ >\ /etc/hostname
+  - action: run
+    chroot: true
+    command: echo debian > /etc/hostname
 
-\ \ \-\ action:\ pack
-\ \ \ \ file:\ {{\ $image\ }}
-\ \ \ \ compression:\ gz
-\f[]
+  - action: pack
+    file: {{ $image }}
+    compression: gz
+\f[R]
 .fi
 .PP
-To run it, create a file named \f[C]example.yaml\f[] and run:
+To run it, create a file named \f[C]example.yaml\f[R] and run:
 .IP
 .nf
 \f[C]
-debos\ example.yaml
-\f[]
+debos example.yaml
+\f[R]
 .fi
 .PP
 The final tarball will be named \[lq]debian.tgz\[rq] if you would like
@@ -132,13 +151,13 @@ image like this:
 .IP
 .nf
 \f[C]
-debos\ \-t\ image:"debian\-arm64.tgz"\ example.yaml
-\f[]
+debos -t image:\[dq]debian-arm64.tgz\[dq] example.yaml
+\f[R]
 .fi
 .SH OTHER EXAMPLES
 .PP
 This example builds a customized image for a Raspberry Pi 3.
-https://github.com/go\-debos/debos\-recipes
+https://github.com/go-debos/debos-recipes
 .SH ENVIRONMENT VARIABLES
 .PP
 debos read a predefined list of environment variables from the host and
@@ -154,8 +173,8 @@ The list of environment variables currently exported to fakemachine is:
 .IP
 .nf
 \f[C]
-http_proxy,\ https_proxy,\ ftp_proxy,\ rsync_proxy,\ all_proxy,\ no_proxy
-\f[]
+http_proxy, https_proxy, ftp_proxy, rsync_proxy, all_proxy, no_proxy
+\f[R]
 .fi
 .PP
 While the elements of environ_vars are in lower case, for each element
@@ -164,16 +183,16 @@ propagated to fakemachine.
 So if the host has the environment variables HTTP_PROXY and no_proxy
 defined, both will be propagated to fakemachine respecting the case.
 .PP
-The command line options \[en]environ\-var and \-e can be used to
-specify, overwrite, and unset environment variables for fakemachine with
-the syntax:
+The command line options \[en]environ-var and -e can be used to specify,
+overwrite, and unset environment variables for fakemachine with the
+syntax:
 .PP
-$ debos \-e ENVIRONVAR:VALUE \&...
+$ debos -e ENVIRONVAR:VALUE \&...
 .PP
 To unset an enviroment variable, or in other words, to prevent an
 environment variable to be propagated to fakemachine, use the same
 syntax without a value.
-debos accept multiple \-e simultaneously.
+debos accept multiple -e simultaneously.
 .SH PROXY CONFIGURATION
 .PP
 While the proxy related environment variables are exported from the host
@@ -188,6 +207,21 @@ you may need to check which are the proxy environment variables they
 use.
 Different apps are known to use different environment variable names and
 different case for environment variable names.
-.SH SEE ALSO
-.PP
-fakemachine at https://github.com/go\-debos/fakemachine
+.SH FAKEMACHINE BACKEND
+.PP
+debos (unless running debos with the \f[C]--disable-fakemachine\f[R]
+argument) creates and spawns a virtual machine using
+fakemachine (https://github.com/go-debos/fakemachine) and executes the
+actions defined by the recipe inside the virtual machine.
+This helps ensure recipes are reproducible no matter the host
+environment.
+.PP
+Fakemachine can use different virtualisation backends to spawn the
+virtualmachine, for more information see the documentation under the
+fakemachine repository (https://github.com/go-debos/fakemachine).
+.PP
+By default the backend will automatically be selected based on what is
+supported on the host machine, but this can be overridden using the
+\f[C]--fakemachine-backend\f[R] option.
+If no backends are supported, debos reverts to running the recipe on the
+host without creating a fakemachine.