Merge pull request #4077 from deitch/docker-bump

bump docker deps to v27.2.0

.circleci/config.yml

@@ -1,62 +0,0 @@
-version: 2
-jobs:
-  build:
-    working_directory: /go/src/github.com/linuxkit/linuxkit
-    docker:
-      - image: circleci/golang:1.9-stretch
-    steps:
-      - checkout
-      - run: mkdir -p ./bin
-      - run:
-          name: Versions
-          command: |
-            set -x
-            go version
-            cat /etc/os-release
-      - run:
-          name: Dependencies
-          command: |
-            go get -u github.com/golang/lint/golint
-            go get -u github.com/gordonklaus/ineffassign
-      - run:
-          name: Lint
-          command: make local-check
-      - run:
-          name: Build amd64/linux
-          environment:
-            GOOS: linux
-            GOARCH: amd64
-          command: make LOCAL_TARGET=bin/linuxkit-$GOOS-$GOARCH local-build
-      - run:
-          name: Build arm64/linux
-          environment:
-            GOOS: linux
-            GOARCH: arm64
-          command: make LOCAL_TARGET=bin/linuxkit-$GOOS-$GOARCH local-build
-      - run:
-          name: Build s390x/linux
-          environment:
-            GOOS: linux
-            GOARCH: s390x
-          command: make LOCAL_TARGET=bin/linuxkit-$GOOS-$GOARCH local-build
-      - run:
-          name: Build amd64/darwin
-          environment:
-            GOOS: darwin
-            GOARCH: amd64
-          command: make LOCAL_TARGET=bin/linuxkit-$GOOS-$GOARCH local-build
-      - run:
-          name: Build amd64/windows
-          environment:
-            GOOS: windows
-            GOARCH: amd64
-          command: make LOCAL_TARGET=bin/linuxkit-$GOOS-$GOARCH.exe local-build
-      - run:
-          name: Test
-          command: make local-test
-      - run:
-          name: Checksum
-          command: cd bin && sha256sum linuxkit-*-* > SHA256SUM
-      - store_artifacts:
-          path: ./bin
-          destination: .

.github/workflows/ci.yml

@@ -0,0 +1,434 @@
+name: LinuxKit CI
+on: [push, pull_request]
+
+jobs:
+  build:
+    name: Build & Test
+    strategy:
+      matrix:
+        target:
+          - os: linux
+            arch: amd64
+            suffix: amd64-linux
+            runner: ubuntu-latest
+          - os: linux
+            arch: arm64
+            suffix: arm64-linux
+            runner: ubuntu-latest
+          - os: linux
+            arch: s390x
+            suffix: s390x-linux
+            runner: ubuntu-latest
+          - os: darwin
+            arch: amd64
+            suffix: amd64-darwin
+            runner: macos-latest
+          - os: darwin
+            arch: arm64
+            suffix: arm64-darwin
+            runner: macos-latest
+          - os: windows
+            arch: amd64
+            suffix: amd64-windows.exe
+            runner: ubuntu-latest
+
+    runs-on: ${{ matrix.target.runner }}
+    steps:
+
+    - name: Set up Go 1.22
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.22.3
+      id: go
+
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Set path
+      run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+      env:
+         GOPATH: ${{runner.workspace}}
+
+    - name: golangci-lint CLI
+      uses: golangci/golangci-lint-action@v6
+      with:
+        version: v1.59.0
+        working-directory: src/cmd/linuxkit
+        args: --verbose --timeout=10m
+    - name: go vet CLI
+      run: |
+        cd src/cmd/linuxkit && go vet ./...
+    - name: Build
+      run: |
+        make GOARCH=${{matrix.target.arch}} GOOS=${{matrix.target.os}} LOCAL_TARGET=$(pwd)/bin/linuxkit-${{matrix.target.suffix}} local-build
+        file bin/linuxkit-${{matrix.target.suffix}}
+      env:
+        GOPATH: ${{runner.workspace}}
+
+    - name: Checksum
+      run: |
+        cd bin
+        if command -v sha256sum > /dev/null; then sha256sum linuxkit-${{matrix.target.suffix}} > linuxkit-${{matrix.target.suffix}}.SHA256SUM
+        else openssl sha256 -r linuxkit-${{matrix.target.suffix}} | tr -d '*'  > linuxkit-${{matrix.target.suffix}}.SHA256SUM
+        fi
+        cat linuxkit-${{matrix.target.suffix}}.SHA256SUM
+
+    - name: Test
+      run: make local-test
+      env:
+        GOPATH: ${{runner.workspace}}
+
+    - name: Upload binary
+      uses: actions/upload-artifact@v4
+      with:
+        name: linuxkit-${{matrix.target.suffix}}
+        path: |
+          bin/linuxkit-${{matrix.target.suffix}}
+          bin/linuxkit-${{matrix.target.suffix}}.SHA256SUM
+        if-no-files-found: error
+
+  build_packages:
+    name: Build Packages
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Set up binfmt
+      # Only register arm64 as we are on amd64 already. s390x is not reliable
+      run: docker run --privileged --rm tonistiigi/binfmt --install arm64
+
+    - name: Download linuxkit
+      uses: actions/download-artifact@v4
+      with:
+        name: linuxkit-amd64-linux
+        path: bin
+
+    - name: Symlink Linuxkit
+      run: |
+        chmod ugo+x bin/linuxkit-amd64-linux
+        sudo ln -s $(pwd)/bin/linuxkit-amd64-linux /usr/local/bin/linuxkit
+        /usr/local/bin/linuxkit version
+
+    - name: Cache Packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.linuxkit/cache/
+        key: ${{ runner.os }}-linuxkit-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-linuxkit-
+
+    - name: Build Packages
+      # Skip s390x as emulation is unreliable
+      run: |
+        make OPTIONS="-v --skip-platforms linux/s390x" -C pkg build
+
+    - name: Build Test Packages
+      # ensures that the test packages are in linuxkit cache when we need them for tests later
+      # Skip s390x as emulation is unreliable
+      run: |
+        make OPTIONS="-v --skip-platforms linux/s390x" -C test/pkg build
+
+    - name: Check Kernel Dependencies up to date
+      # checks that any kernel dependencies are up to date.
+      # if they are, then running `make update-kernel-yamls` will not change anything
+      run: |
+        echo "checking git diff before running make update-kernel-yamls"
+        git diff --exit-code
+        echo "running make update-kernel-yamls"
+        make -C kernel update-kernel-yamls
+        echo "checking git diff again after running make update-kernel-yamls; should be no changes"
+        git diff --exit-code
+
+    - name: Build Kernels
+      # ensures that the kernel packages are in linuxkit cache when we need them for tests later
+      # no need for excluding s390x, as each build.yml in the kernel explicitly lists archs
+      run: |
+        make OPTIONS="-v" -C kernel build
+
+    - name: list cache contents
+      run: |
+        linuxkit cache ls
+
+  test_packages:
+    name: Packages Tests
+    needs: [ build_packages, build ]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shard: [1/10,2/10,3/10,4/10,5/10,6/10,7/10,8/10,9/10,10/10]
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Install Pre-Requisites
+      run: |
+        export DEBIAN_FRONTEND=noninteractive
+        sudo apt-get update
+        sudo apt-get install -qy qemu-utils qemu-system-x86 expect
+
+    - name: Restore RTF From Cache
+      id: cache-rtf
+      uses: actions/cache@v4
+      with:
+        path: bin
+        key: rtf-${{hashFiles('Makefile')}}
+
+    - name: Build RTF
+      if: steps.cache-rtf.outputs.cache-hit != 'true'
+      run: make bin/rtf
+
+    - name: Symlink RTF
+      run: |
+        sudo ln -s $(pwd)/bin/rtf /usr/local/bin/rtf
+
+    - name: Download linuxkit
+      uses: actions/download-artifact@v4
+      with:
+        name: linuxkit-amd64-linux
+        path: bin
+
+    - name: Symlink Linuxkit
+      run: |
+        chmod ugo+x bin/linuxkit-amd64-linux
+        sudo ln -s $(pwd)/bin/linuxkit-amd64-linux /usr/local/bin/linuxkit
+        /usr/local/bin/linuxkit version
+
+    - name: Restore Package Cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.linuxkit/cache/
+        key: ${{ runner.os }}-linuxkit-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-linuxkit-
+    - name: list cache contents
+      run: |
+        linuxkit cache ls
+      
+    - name: Run Tests
+      run: make test TEST_SUITE=linuxkit.packages TEST_SHARD=${{ matrix.shard }}
+
+  test_kernel:
+    name: Kernel Tests
+    needs: [ build_packages, build ]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Install Pre-Requisites
+      run: |
+        export DEBIAN_FRONTEND=noninteractive
+        sudo apt-get update
+        sudo apt-get install -qy qemu-utils qemu-system-x86 expect
+
+    - name: Restore RTF From Cache
+      id: cache-rtf
+      uses: actions/cache@v4
+      with:
+        path: bin
+        key: rtf-${{hashFiles('Makefile')}}
+
+    - name: Build RTF
+      if: steps.cache-rtf.outputs.cache-hit != 'true'
+      run: make bin/rtf
+
+    - name: Symlink RTF
+      run: |
+        sudo ln -s $(pwd)/bin/rtf /usr/local/bin/rtf
+
+    - name: Download linuxkit
+      uses: actions/download-artifact@v4
+      with:
+        name: linuxkit-amd64-linux
+        path: bin
+
+    - name: Symlink Linuxkit
+      run: |
+        chmod ugo+x bin/linuxkit-amd64-linux
+        sudo ln -s $(pwd)/bin/linuxkit-amd64-linux /usr/local/bin/linuxkit
+        /usr/local/bin/linuxkit version
+
+    - name: Restore Package Cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.linuxkit/cache/
+        key: ${{ runner.os }}-linuxkit-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-linuxkit-
+
+    - name: list cache contents
+      run: |
+        linuxkit cache ls
+      
+    - name: Run Tests
+      run: make test TEST_SUITE=linuxkit.kernel
+
+  test_linuxkit:
+    name: LinuxKit Build Tests
+    needs: [ build_packages, build ]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Install Pre-Requisites
+      run: |
+        export DEBIAN_FRONTEND=noninteractive
+        sudo apt-get update
+        sudo apt-get install -qy qemu-utils qemu-system-x86 expect
+
+    - name: Restore RTF From Cache
+      id: cache-rtf
+      uses: actions/cache@v4
+      with:
+        path: bin
+        key: rtf-${{hashFiles('Makefile')}}
+
+    - name: Restore Package Cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.linuxkit/cache/
+        key: ${{ runner.os }}-linuxkit-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-linuxkit-
+
+    - name: Build RTF
+      if: steps.cache-rtf.outputs.cache-hit != 'true'
+      run: make bin/rtf
+
+    - name: Symlink RTF
+      run: |
+        sudo ln -s $(pwd)/bin/rtf /usr/local/bin/rtf
+
+    - name: Download linuxkit
+      uses: actions/download-artifact@v4
+      with:
+        name: linuxkit-amd64-linux
+        path: bin
+
+    - name: Symlink Linuxkit
+      run: |
+        chmod ugo+x bin/linuxkit-amd64-linux
+        sudo ln -s $(pwd)/bin/linuxkit-amd64-linux /usr/local/bin/linuxkit
+        /usr/local/bin/linuxkit version
+
+    - name: list cache contents
+      run: |
+        linuxkit cache ls
+  
+    - name: Run Tests
+      run: make test TEST_SUITE=linuxkit.build
+
+  test_platforms:
+    name: Platform Tests
+    needs: [ build_packages, build ]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Install Pre-Requisites
+      run: |
+        export DEBIAN_FRONTEND=noninteractive
+        sudo apt-get update
+        sudo apt-get install -qy qemu-utils qemu-system-x86 expect
+
+    - name: Restore RTF From Cache
+      id: cache-rtf
+      uses: actions/cache@v4
+      with:
+        path: bin
+        key: rtf-${{hashFiles('Makefile')}}
+
+    - name: Build RTF
+      if: steps.cache-rtf.outputs.cache-hit != 'true'
+      run: make bin/rtf
+
+    - name: Symlink RTF
+      run: |
+        sudo ln -s $(pwd)/bin/rtf /usr/local/bin/rtf
+
+    - name: Download linuxkit
+      uses: actions/download-artifact@v4
+      with:
+        name: linuxkit-amd64-linux
+        path: bin
+
+    - name: Symlink Linuxkit
+      run: |
+        chmod ugo+x bin/linuxkit-amd64-linux
+        sudo ln -s $(pwd)/bin/linuxkit-amd64-linux /usr/local/bin/linuxkit
+        /usr/local/bin/linuxkit version
+
+    - name: Restore Package Cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.linuxkit/cache/
+        key: ${{ runner.os }}-linuxkit-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-linuxkit-
+
+    - name: list cache contents
+      run: |
+        linuxkit cache ls
+      
+    - name: Run Tests
+      run: make test TEST_SUITE=linuxkit.platforms
+
+  test_security:
+    name: Security Tests
+    needs: [ build_packages, build ]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Install Pre-Requisites
+      run: |
+        export DEBIAN_FRONTEND=noninteractive
+        sudo apt-get update
+        sudo apt-get install -qy qemu-utils qemu-system-x86 expect
+
+    - name: Restore RTF From Cache
+      id: cache-rtf
+      uses: actions/cache@v4
+      with:
+        path: bin
+        key: rtf-${{hashFiles('Makefile')}}
+
+    - name: Build RTF
+      if: steps.cache-rtf.outputs.cache-hit != 'true'
+      run: make bin/rtf
+
+    - name: Symlink RTF
+      run: |
+        sudo ln -s $(pwd)/bin/rtf /usr/local/bin/rtf
+
+    - name: Download linuxkit
+      uses: actions/download-artifact@v4
+      with:
+        name: linuxkit-amd64-linux
+        path: bin
+
+    - name: Symlink Linuxkit
+      run: |
+        chmod ugo+x bin/linuxkit-amd64-linux
+        sudo ln -s $(pwd)/bin/linuxkit-amd64-linux /usr/local/bin/linuxkit
+        /usr/local/bin/linuxkit version
+
+    - name: Restore Package Cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.linuxkit/cache/
+        key: ${{ runner.os }}-linuxkit-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-linuxkit-
+
+    - name: list cache contents
+      run: |
+        linuxkit cache ls
+      
+    - name: Run Tests
+      run: make test TEST_SUITE=linuxkit.security

.github/workflows/package_release.yml

@@ -0,0 +1,38 @@
+name: Release Tagged Packages
+
+on:
+  create:
+
+jobs:
+  release:
+    name: Release packages
+    if: github.ref_type == 'tag' && startsWith(github.ref, 'refs/tags/pkg-v')
+    runs-on: ubuntu-latest
+    steps:
+    - name: Set up Go 1.22
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.22.3
+      id: go
+    - name: Check out code
+      uses: actions/checkout@v4
+    - name: Ensure bin/ directory
+      run: mkdir -p bin
+    - name: Install linuxkit
+      run: |
+        go -C ./src/cmd/linuxkit build -o $(pwd)/bin/linuxkit 
+        sudo mv bin/linuxkit /usr/local/bin/
+    - name: Login to Docker Hub
+      uses: docker/login-action@v2
+      with:
+        username: ${{ secrets.DOCKERHUB_USERNAME }}
+        password: ${{ secrets.DOCKERHUB_TOKEN }}
+    - name: Publish Packages as Release
+      # this should not build anything, as they all should be built already
+      # however, it can fail if we push the tag before the merge-to-master build is complete, since that may publish
+      # so *always* wait for any merge-to-master to complete before publishing pkg-v* tags
+      run: |
+        RELEASE_TAG=${GITHUB_REF#refs/tags/pkg-}
+        echo "RELEASE_TAG=${RELEASE_TAG}"
+        [ -n "${RELEASE_TAG}" ] || { echo "Not a tag"; exit 1; }
+        make OPTIONS="--skip-platforms linux/s390x" -C pkg push PUSHOPTIONS="--nobuild --release ${RELEASE_TAG}"

.github/workflows/publish.yaml

@@ -0,0 +1,74 @@
+# publish changes that are merged to master
+name: Packages Push
+on:
+  workflow_run:
+    workflows: [LinuxKit CI]
+    types: [completed]
+    branches: [master, main]
+
+jobs:
+  packages:
+    env:
+      linuxkit_file: linuxkit-amd64-linux
+    name: Publish Changed Packages
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+    - name: Ensure bin/ directory
+      run: mkdir -p bin
+    - name: Download linuxkit
+      uses: actions/github-script@v7
+      with:
+        github-token: ${{secrets.GITHUB_TOKEN}}
+        script: |
+          var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: ${{github.event.workflow_run.id }},
+          });
+          var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
+            return artifact.name == "${{ env.linuxkit_file }}"
+          })[0];
+          var download = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: matchArtifact.id,
+              archive_format: 'zip',
+          });
+          var fs = require('fs');
+          fs.writeFileSync('${{github.workspace}}/bin/${{ env.linuxkit_file }}.zip', Buffer.from(download.data));
+    - name: unzip linuxkit
+      run: cd bin && unzip ${{ env.linuxkit_file }}.zip
+    - name: Symlink Linuxkit
+      run: |
+        chmod ugo+x bin/${{ env.linuxkit_file }}
+        sudo ln -s $(pwd)/bin/${{ env.linuxkit_file }} /usr/local/bin/linuxkit
+        /usr/local/bin/linuxkit version
+    - name: Restore Package Cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.linuxkit/cache/
+        key: ${{ runner.os }}-linuxkit-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-linuxkit-
+    - name: Login to Docker Hub
+      uses: docker/login-action@v2
+      with:
+        username: ${{ secrets.DOCKERHUB_USERNAME }}
+        password: ${{ secrets.DOCKERHUB_TOKEN }}
+    - name: Publish Packages
+      # this should only push changed ones:
+      #  - unchanged: already in the registry
+      #  - changed: already built and cached, so only will push
+      # Skip s390x as emulation is unreliable
+      run: |
+        make OPTIONS="--skip-platforms linux/s390x" -C pkg push PUSHOPTIONS="--nobuild"
+
+    - name: Publish Kernels
+      # this should only push changed ones:
+      #  - unchanged: already in the registry
+      #  - changed: already built and cached, so only will push
+      # No need to skip s390x, since kernel build.yml files all have explicit archs
+      run: |
+        make -C kernel push

.github/workflows/release.yml

@@ -0,0 +1,97 @@
+name: Release Tagged Linuxkit
+
+on:
+  create:
+
+jobs:
+  build-all:
+    name: Build all targets expect macOS
+    if: github.ref_type == 'tag' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Set up Go 1.122
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.22.3
+      id: go
+
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Set path
+      run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+      env:
+         GOPATH: ${{runner.workspace}}
+
+    - name: Build
+      run: |
+        make build-targets-linux build-targets-windows
+      env:
+        GOPATH: ${{runner.workspace}}
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: release-targets-except-cgo
+        path: bin/
+  
+  # separate macos build because macos needs CGO, and it is very hard to cross-compile that
+  build-macos:
+    name: Build macOS target
+    if: github.ref_type == 'tag' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: macos-latest
+    steps:
+
+    - name: Set up Go 1.122
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.22.3
+      id: go
+
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Set path
+      run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+      env:
+         GOPATH: ${{runner.workspace}}
+
+    - name: Build
+      run: |
+        make build-targets-macos
+      env:
+        GOPATH: ${{runner.workspace}}
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: release-targets-macos
+        path: bin/
+    
+  release-artifacts:
+    needs: [build-all, build-macos]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/download-artifact@v4
+      with:
+        name: release-targets-except-cgo
+        path: bintmp/release-targets-except-cgo
+    - uses: actions/download-artifact@v4
+      with:
+        name: release-targets-macos
+        path: bintmp/release-targets-macos
+    - name: Combine Artifacts
+      run: |
+        mkdir -p bin/
+        cp bintmp/*/* bin/
+    - name: Checksum Artifacts
+      run: |
+        make checksum-targets
+    - name: GitHub Release
+      uses: softprops/action-gh-release@1e07f4398721186383de40550babbdf2b84acfc5
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        draft: true
+        files: bin/*
+        generate_release_notes: true

.gitignore

@@ -19,3 +19,4 @@ Dockerfile.media
 *-cmdline
 *-state
 artifacts/*
+tools/alpine/iid

.mailmap

@@ -1,5 +1,3 @@
-# Generate AUTHORS: scripts/generate-authors.sh
-
 # Tip for finding duplicates (besides scanning the output of AUTHORS for name
 # duplicates that aren't also email duplicates): scan the output of:
 #   git log --format='%aE - %aN' | sort -uf
@@ -7,6 +5,7 @@
 # For explanation on this file format: man git-shortlog
 
 Alice Frosi <alice@linux.vnet.ibm.com> <alice@linux.vnet.ibm.comx>
+Alice Frosi <alice@linux.vnet.ibm.com> <afrosi@de.ibm.com>
 Amir Chaudhry <amir.chaudhry@docker.com> <amirmc@gmail.com>
 Anil Madhavapeddy <anil.madhavapeddy@docker.com> <anil@recoil.org>
 Dan Finneran <dan@thebsdbox.co.uk> <dan@dev.fnnrn.me>
@@ -21,21 +20,27 @@ Dave Tucker <dt@docker.com> <dave@dtucker.co.uk>
 David Gageot <david.gageot@docker.com> <david@gageot.net>
 David Sheets <david.sheets@docker.com> <dsheets@docker.com>
 David Sheets <david.sheets@docker.com> <sheets@alum.mit.edu>
+Eric Briand <eric.briand@gmail.com>
 Ian Campbell <ian.campbell@docker.com> <ijc25@users.noreply.github.com>
 Ian Campbell <ian.campbell@docker.com> <ijc@docker.com>
 Ian Campbell <ian.campbell@docker.com> <ijc@users.noreply.github.com>
+Ian Campbell <ian.campbell@docker.com> <ijc@lxdeb01.marist.edu>
 Isaac Rodman <isaac@eyz.us> <isaac.rodman@healthtrio.com>
 Isaac Rodman <isaac@eyz.us>
 Istvan Szukacs <l1x@users.noreply.github.com>
+James McCoy <james@mcy.email>
 Jeff Wu <jeff.wu.junfei@gmail.com> <JeffWuBJ@users.noreply.github.com>
 Jeremy Yallop <yallop@docker.com> <yallop@gmail.com>
 Justin Cormack <justin.cormack@docker.com> <justin.cormack@unikernel.com>
 Justin Cormack <justin.cormack@docker.com> <justin@specialbusservice.com>
+Justin Barrick <jbarrick@cloudflare.com>
 Ken Cochrane <ken.cochrane@docker.com> <KenCochrane@gmail.com>
 Magnus Skjegstad <magnus.skjegstad@docker.com> <magnus@skjegstad.com>
 Marten Cassel <marten.cassel@gmail.com> <mcpop28@hotmail.com>
 Mindy Preston <mindy.preston@docker.com> <meetup@yomimono.org>
-Nathan Dautenhahn <ndd@seas.upenn.edu> <ndd@cis.upenn.edu>
+MinJae Kwon <mingrammer@gmail.com>
+Nathan Dautenhahn <ndd@rice.edu> <ndd@seas.upenn.edu>
+Nathan Dautenhahn <ndd@rice.edu> <ndd@cis.upenn.edu>
 Nathan LeClaire <nathan.leclaire@docker.com> <nathan.leclaire@gmail.com>
 Nathan LeClaire <nathan.leclaire@docker.com> <nathanleclaire@gmail.com>
 Niclas Mietz <niclas@mietz.io>
@@ -44,9 +49,10 @@ Radu Matei <matei.radu94@gmail.com>
 Riyaz Faizullabhoy <riyaz.faizullabhoy@docker.com> <riyazdf@berkeley.edu>
 Riyaz Faizullabhoy <riyaz.faizullabhoy@docker.com> <riyazdf@gmail.com>
 Robin Winkelewski <w9ncontact@gmail.com>
-Rolf Neugebauer <rolf.neugebauer@docker.com> <rneugeba@users.noreply.github.com>
-Rolf Neugebauer <rolf.neugebauer@docker.com> <rn@users.noreply.github.com>
-Rolf Neugebauer <rolf.neugebauer@docker.com> <rolf.neugebauer@gmail.com>
+Rolf Neugebauer <rn@rneugeba.io> <rneugeba@users.noreply.github.com>
+Rolf Neugebauer <rn@rneugeba.io> <rn@users.noreply.github.com>
+Rolf Neugebauer <rn@rneugeba.io> <rolf.neugebauer@gmail.com>
+Rolf Neugebauer <rn@rneugeba.io> <rolf.neugebauer@docker.com>
 Sebastiaan van Stijn <sebastiaan.vanstijn@docker.com> <github@gone.nl>
 Simon Ferquel <simon.ferquel@docker.com> <simon.ferquel@hotmail.fr>
 Thomas Gazagnaire <thomas.gazagnaire@docker.com> <thomas@gazagnaire.com>

ADOPTERS.md

@@ -0,0 +1,19 @@
+## LinuxKit Adopters
+
+_This list is currently under construction. Please add your use cases to this with a PR. Thanks!_
+
+# Production Users
+
+**_[Docker Desktop](https://www.docker.com/products/docker-desktop)_** - Docker Desktop for Mac and Windows uses LinuxKit to provide an embedded, invisible virtual machine in order to run Linux containers and to run Kubernetes. There are currently millions of active users.
+
+**_[TagHub](https://www.taghub.net)_** - TagHub is a SaaS product for doing asset management. We use LinuxKit to have small and secure linux nodes powering our multi-cloud infrastructure. TagHub is made by [Smart Management](http://www.smartm.no/).
+
+# Projects Using LinuxKit
+
+**_[LinuxKit Nix](https://github.com/nix-community/linuxkit-nix)_** aims to provide a Linux Nix VM for macOS.
+
+**_[cfdev](https://github.com/cloudfoundry-incubator/cfdev)_** A fast and easy local Cloud Foundry experience on native hypervisors, powered by LinuxKit with VPNKit
+
+**_[dm-linuxkit](https://github.com/dotmesh-io/dm-linuxkit)_** A dotmesh controller for LinuxKit persistent storage management.
+
+**_[Linux Foundation Edge EVE](https://github.com/lf-edge/eve)_** Edge Virtualization Engine Operating System

AUTHORS

@@ -3,17 +3,31 @@
 
 Ajeet Singh Raina, Docker Captain, {Code} Catalysts, Dell EMC R&D <ajeetraina@gmail.com>
 Akihiro Suda <suda.akihiro@lab.ntt.co.jp>
+Alan Raison <alanraison@users.noreply.github.com>
+Alex Ellis <alexellis2@gmail.com>
 Alex Johnson <hello@alex-johnson.net>
+Alex Szakaly <alex.szakaly@gmail.com>
+Alexander Slesarev <alex.slesarev@nudatasecurity.com>
 Alice Frosi <alice@linux.vnet.ibm.com>
 Amir Chaudhry <amir.chaudhry@docker.com>
 Anil Madhavapeddy <anil.madhavapeddy@docker.com>
+Arthur Lutz <arthur.lutz@logilab.fr>
+Asbjorn Enge <asbjorn@hanafjedle.net>
 Avi Deitcher <avi@deitcher.net>
+Aymen EL AMRI <aymen@eralabs.io>
+Ben Allen <bsallen@alcf.anl.gov>
 Bill Kerr <bill@generalbill.com>
+Björn Ingeson <bjorn.ingeson@gmail.com>
+Brice Figureau <brice-puppet@daysofwonder.com>
 Carlton-Semple <carlton.semple@ibm.com>
+Chanwit Kaewkasi <chanwit@gmail.com>
+Christian Wuerdig <christian.wuerdig@gmail.com>
+Clovis Durand <cd.clovel19@gmail.com>
 Craig Ingram <cingram@heroku.com>
 Damiano Donati <damiano.donati@gmail.com>
 Dan Finneran <dan@thebsdbox.co.uk>
 Daniel Caminada <daniel.caminada@ergon.ch>
+Daniel Dean <daniel@razorsecure.com>
 Daniel Hiltgen <daniel.hiltgen@docker.com>
 Daniel Nephin <dnephin@gmail.com>
 Dave Freitag <dcfreita@us.ibm.com>
@@ -25,74 +39,108 @@ David Scott <dave.scott@docker.com>
 David Sheets <david.sheets@docker.com>
 Dennis Chen <dennis.chen@arm.com>
 Dieter Reuter <dieter.reuter@me.com>
+Dominic White <singe-github@singe.za.net>
+duraki <duraki@linuxmail.org>
 Edward Vielmetti <edward.vielmetti@gmail.com>
 Emily Casey <ecasey@pivotal.io>
 Eric Briand <eric.briand@gmail.com>
+Evan Hazlett <ejhazlett@gmail.com>
+Federico Pellegatta <12744504+federico-pellegatta@users.noreply.github.com>
 French Ben <frenchben@docker.com>
+Frédéric Dalleau <frederic.dalleau@docker.com>
 functor <meehow@gmail.com>
+Gabriel Chabot <gabriel.chabot@qarnot-computing.com>
 Garth Bushell <garth.bushell@oracle.com>
 George Papanikolaou <g3orge.app@gmail.com>
+Gerben Geijteman <gerben@isset.nl>
 Gianluca Arbezzano <gianarb92@gmail.com>
 Guillaume Rose <guillaume.rose@docker.com>
 Hans van den Bogert <hansbogert@gmail.com>
+hyperized <gerben@hyperized.net>
 Ian Campbell <ian.campbell@docker.com>
 Ilya Dmitrichenko <errordeveloper@gmail.com>
 Isaac Rodman <isaac@eyz.us>
 Istvan Szukacs <l1x@users.noreply.github.com>
+Ivan Markin <sw@nogoegst.net>
+James McCoy <james@mcy.email>
 Jason A. Donenfeld <Jason@zx2c4.com>
 Jeff Wu <jeff.wu.junfei@gmail.com>
 Jeffrey Hogan <jeff.hogan1@gmail.com>
 Jeremy Yallop <yallop@docker.com>
 Jes Ferrier <jes.ferrier@gmail.com>
 Jesse Adametz <jesseadametz@gmail.com>
+Johannes Würbach <johannes.wuerbach@googlemail.com>
 John Albietz <inthecloud247@gmail.com>
 Jose Carlos Venegas Munoz <jose.carlos.venegas.munoz@intel.com>
+Justin Barrick <jbarrick@cloudflare.com>
 Justin Cormack <justin.cormack@docker.com>
 Justin Ko <justin.ko@oracle.com>
+Justin Terry (VM) <juterry@microsoft.com>
+Karol Woźniak <wozniakk@gmail.com>
 Ken Cochrane <ken.cochrane@docker.com>
+Krister Johansen <krister.johansen@oracle.com>
+Krisztian Horvath <keyki.kk@gmail.com>
 Kunal Kushwaha <kushwaha_kunal_v7@lab.ntt.co.jp>
 Liqdfire <liqdfire@gmail.com>
 Lorenzo Fontana <lo@linux.com>
+Loïc Pottier <lpottier@isi.edu>
 Luke Hodkinson <furious.luke@gmail.com>
 Madhu Venugopal <madhu@docker.com>
 Magnus Skjegstad <magnus.skjegstad@docker.com>
 Marco Mariani <marco.mariani@alterway.fr>
 Marcus van Dam <marcus@marcusvandam.nl>
+Mario Loriedo <mario.loriedo@gmail.com>
 marten <marten.cassel@gmail.com>
+Mathieu Champlon <mathieu.champlon@docker.com>
 Mathieu Pasquet <mathieu.pasquet@alterway.fr>
 Matt Bajor <matt.bajor@workday.com>
 Matt Bentley <matt.bentley@docker.com>
 Matt Johnson <matjohn2@cisco.com>
+Michael Aldridge <aldridge.mac@gmail.com>
 Michel Courtine <michel.courtine@docker.com>
 Mickaël Salaün <mic@digikod.net>
 Mindy Preston <mindy.preston@docker.com>
+MinJae Kwon <mingrammer@gmail.com>
 Natanael Copa <natanael.copa@docker.com>
-Nathan Dautenhahn <ndd@seas.upenn.edu>
+Nathan Dautenhahn <ndd@rice.edu>
 Nathan LeClaire <nathan.leclaire@docker.com>
 Nick Jones <nick@dischord.org>
 Niclas Mietz <niclas@mietz.io>
 Nico Di Rocco <dirocco.nico@gmail.com>
 Olaf Bergner <olaf.bergner@gmx.de>
 Olaf Flebbe <of@oflebbe.de>
+Omar Ramadan <omar.ramadan93@gmail.com>
+Patrik Cyvoct <patrik@ptrk.io>
+Petr Fedchenkov <giggsoff@gmail.com>
 Phil Estes <estesp@linux.vnet.ibm.com>
 Pierre Gayvallet <pierre.gayvallet@docker.com>
 Pratik Mallya <mallya@us.ibm.com>
+Preston Holmes <preston@ptone.com>
 Radu Matei <matei.radu94@gmail.com>
+Richard Connon <richard@connon.me.uk>
 Richard Mortier <mort@cantab.net>
 Riyaz Faizullabhoy <riyaz.faizullabhoy@docker.com>
 Robb Kistler <robb.kistler@docker.com>
 Robin Winkelewski <w9ncontact@gmail.com>
-Rolf Neugebauer <rolf.neugebauer@docker.com>
+Rolf Neugebauer <rn@rneugeba.io>
 Roman Shaposhnik <rvs@zededa.com>
 Rui Lopes <rgl@ruilopes.com>
 Ryoga Saito <proelbtn@gmail.com>
+Sachi King <nakato@nakato.io>
+salman aljammaz <s@aljmz.com>
+schrotthaufen <schrotthaufen@invalid.invalid>
 Scott Coulton <scott.coulton@puppet.com>
 Sebastiaan van Stijn <sebastiaan.vanstijn@docker.com>
+sethp <seth.pellegrino@gmail.com>
+Simarpreet Singh <simar@linux.com>
 Simon Ferquel <simon.ferquel@docker.com>
+Simon Fridlund <simon@fridlund.email>
 Sotiris Salloumis <sotiris.salloumis@gmail.com>
+Steeve Morin <steeve.morin@gmail.com>
 Stefan Bourlon <stefan.bourlon@ca.com>
 Stephen J Day <stephen.day@docker.com>
 Steve Hiehn <shiehn@pivotal.io>
+Sukchan Lee <acetcom@gmail.com>
 Theo Koulouris <theo.koulouris@hpe.com>
 Thomas Conte <thomas@conte.com>
 Thomas Gazagnaire <thomas.gazagnaire@docker.com>
@@ -101,8 +149,13 @@ Thomas Shaw <tomwillfixit@users.noreply.github.com>
 Tiago Pires <tandrepires@gmail.com>
 Tiejun Chen <tiejun.china@gmail.com>
 Tim Potter <tpot@hpe.com>
+Tobias Gesellchen <tobias@gesellix.de>
 Tobias Klauser <tklauser@distanz.ch>
+Tomas Knappek <tomas.knappek@gmail.com>
+Tristan Slominski <tristan.slominski@gmail.com>
 Tycho Andersen <tycho@docker.com>
 Vincent Demeester <Vincent.Demeester@docker.com>
+Yoann Ricordel <yoann.ricordel@qarnot-computing.com>
 Zachery Hostens <zacheryph@gmail.com>
+zimbatm <zimbatm@zimbatm.com>
 zlim <zlim.lnx@gmail.com>

CHANGELOG.md

@@ -3,6 +3,93 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 
+## [v0.8] - 2020-05-10
+### Added
+
+- Removed dependency on external `notary` and `manifest-tool` binaries for package builds
+- Risc-V support for `binfmt`
+- Support for GPT partitions
+- `metadata` package support for Digital Ocean and Hetzner as well as loading from a file
+- Support for `/sys/fs/bpf` in `init`
+- Github Actions for CI
+
+### Changed
+- `alpine` base updated to 3.11
+- `containerd` updated to v1.3.4
+- `runc` updated to v1.0.0-rc9
+- `binfmt` updated to qemu 4.2
+- `node_exporter` updated to  v0.18.1
+- `cadvisor` updated to v0.36.0
+- WireGuard updated to 1.0.20200319
+- Improved CDROM support and fixes to GCP and Scaleway providers in the `metadata` package
+- Improved creation of `swap` files
+- Improved RPI3 build
+
+### Removed
+- Containerized `qemu`
+- Windows binary from release
+
+## [v0.7] - 2019-04-17
+### Added
+- Reproducible `linuxkit build` for some output formats
+- Support uncompressed kernels, e.g., for crosvm and firecracker.
+- Support encrypted disks via `dm-crypt`
+- New `bpftrace` package
+- Support for USB devices in `qemu`
+
+### Changed
+- Alpine base updated to 3.9
+- `containerd` updated to v1.2.6
+- WireGuard updated to 0.0.20190227
+- Updated Docker base API level
+- VirtualBox improvements (multiple drives and network adapters)
+- Fixed Windows path handling in `linuxkit`
+- GCP: Improve error checking/handling
+
+### Removed
+
+
+## [v0.6] - 2018-07-26
+### Added
+- `linuxkit build` now works with private repositories and registries.
+- `linuxkit pkg build` can build packages with sources outside the package directory.
+- New `kernel+iso` format for `linuxkit build`.
+
+### Changed
+- `containerd` updated to v1.1.2.
+- WireGuard updated to 0.0.20180718.
+- Fixed SSH key handling on GCP.
+- Changed name of logfiles when memlogd/logwrite is used.
+- `moby/tool` code merged back into `linuxkit/linuxkit`
+- Smaller `mkimage-*` packages.
+
+### Removed
+
+
+
+## [v0.5] - 2018-07-10
+### Added
+- New logging support with log rotation.
+- Scaleway provider.
+- Support for v4.17.x kernels.
+- Kernel source are now included in the kernel packages.
+- Improved documentation about debugging LinuxKit.
+
+### Changed
+- Switched to Alpine Linux 3.8 as the base.
+- `containerd` updated to v1.1.1.
+- `pkg/cadvisor` updated to v0.30.2
+- `pkg/node_exporter` updated to 0.16.0
+- WireGuard updated to 0.0.20180708.
+- Linux firmware binaries update to latest.
+- Improved support for building on Windows.
+- Improved support for AWS/GCP metadata.
+- Better handling of reboot/poweroff.
+
+### Removed
+- Support for v4.16.x. kernels as they have been EOLed.
+
+
 ## [v0.4] - 2018-05-12
 ### Added
 - Support for v4.16.x kernels.

MAINTAINERS

@@ -159,13 +159,24 @@ on disputes for technical matters."
 [Org]
 	[Org."Core maintainers"]
 		people = [
+			"dave-tucker",
 			"deitch",
+			"djs55",
 			"ijc",
 			"justincormack",
-			"riyazdf",
 			"rn",
 		]
 
+	[Org.Alumni]
+
+	# This list contains maintainers that are no longer active on the project.
+	# It is thanks to these people that the project has become what it is today.
+	# Thank you!
+
+		people = [
+			"riyazdf",
+		]
+
 [people]
 
 # A reference list of all people associated with the project.
@@ -173,11 +184,21 @@ on disputes for technical matters."
 # in the people section.
 
 	# ADD YOURSELF HERE IN ALPHABETICAL ORDER
+	[People.dave-tucker]
+	Name = "Dave Tucker"
+	Email = "dave@dtucker.co.uk"
+	Github = "dave-tucker"
+
 	[People.deitch]
 	Name = "Avi Deitcher"
 	Email = "avi@atomicinc.com"
 	GitHub = "deitch"
 
+	[People.djs55]
+	Name = "David Scott"
+	Email = "dave@recoil.org"
+	Github = "djs55"
+
 	[People.ijc]
 	Name = "Ian Campbell"
 	Email = "ian.campbell@docker.com"
@@ -195,5 +216,5 @@ on disputes for technical matters."
 
 	[people.rn]
 	Name = "Rolf Neugebauer"
-	Email = "rolf.neugebauer@docker.com"
+	Email = "rn@rneugeba.io"
 	GitHub = "rn"

Makefile

@@ -1,17 +1,20 @@
-.DELETE_ON_ERROR:
+VERSION="v0.8+"
 
-.PHONY: default all
-default: bin/linuxkit bin/rtf
-all: default
+# test suite to run, blank for all
+TEST_SUITE ?=
+TEST_SHARD ?=
 
-VERSION="v0.4"
-GIT_COMMIT=$(shell git rev-list -1 HEAD)
+GO_COMPILE=linuxkit/go-compile:c97703655e8510b7257ffc57f25e40337b0f0813
 
-GO_COMPILE=linuxkit/go-compile:a8bffe875268a973ea82e5937b0fb23a5b08cc79
-
-LINUXKIT?=bin/linuxkit
+ifeq ($(OS),Windows_NT)
+LINUXKIT?=$(CURDIR)/bin/linuxkit.exe
+RTF?=bin/rtf.exe
+GOOS?=windows
+else
+LINUXKIT?=$(CURDIR)/bin/linuxkit
+RTF?=bin/rtf
 GOOS?=$(shell uname -s | tr '[:upper:]' '[:lower:]')
-GOARCH?=amd64
+endif
 ifneq ($(GOOS),linux)
 CROSS+=-e GOOS=$(GOOS)
 endif
@@ -19,18 +22,28 @@ ifneq ($(GOARCH),amd64)
 CROSS+=-e GOARCH=$(GOARCH)
 endif
 
-PREFIX?=/usr/local/
+PREFIX?=/usr/local
 
-RTF_COMMIT=171155c375706f2616f0b9c96afe2240e15d1de1
+LOCAL_TARGET?=$(CURDIR)/bin/linuxkit
+
+export VERSION GO_COMPILE GOOS GOARCH LOCAL_TARGET LINUXKIT
+
+.DELETE_ON_ERROR:
+
+.PHONY: default all
+default: linuxkit $(RTF)
+all: default
+
+RTF_COMMIT=b74a4f7c78e5cddcf7e6d2e6be7be312b9f645fc
 RTF_CMD=github.com/linuxkit/rtf/cmd
 RTF_VERSION=0.0
-bin/rtf: tmp_rtf_bin.tar | bin
-	tar xf $<
+$(RTF): tmp_rtf_bin.tar | bin
+	tar -C $(dir $(RTF)) -xf $<
 	rm $<
 	touch $@
 
 tmp_rtf_bin.tar: Makefile
-	docker run --rm --log-driver=none -e http_proxy=$(http_proxy) -e https_proxy=$(https_proxy) $(CROSS) $(GO_COMPILE) --clone-path github.com/linuxkit/rtf --clone https://github.com/linuxkit/rtf.git --commit $(RTF_COMMIT) --package github.com/linuxkit/rtf --ldflags "-X $(RTF_CMD).GitCommit=$(RTF_COMMIT) -X $(RTF_CMD).Version=$(RTF_VERSION)" -o bin/rtf > $@
+	docker run --rm --log-driver=none -e http_proxy=$(http_proxy) -e https_proxy=$(https_proxy) $(CROSS) $(GO_COMPILE) --clone-path github.com/linuxkit/rtf --clone https://github.com/linuxkit/rtf.git --commit $(RTF_COMMIT) --package github.com/linuxkit/rtf --ldflags "-X $(RTF_CMD).GitCommit=$(RTF_COMMIT) -X $(RTF_CMD).Version=$(RTF_VERSION)" -o $(notdir $(RTF)) > $@
 
 # Manifest tool for multi-arch images
 MT_COMMIT=bfbd11963b8e0eb5f6e400afaebeaf39820b4e90
@@ -43,63 +56,33 @@ bin/manifest-tool: tmp_mt_bin.tar | bin
 tmp_mt_bin.tar: Makefile
 	docker run --rm --log-driver=none -e http_proxy=$(http_proxy) -e https_proxy=$(https_proxy) $(CROSS) $(GO_COMPILE) --clone-path github.com/estesp/manifest-tool --clone $(MT_REPO) --commit $(MT_COMMIT) --package github.com/estesp/manifest-tool --ldflags "-X main.gitCommit=$(MT_COMMIT)" -o bin/manifest-tool > $@
 
-LINUXKIT_DEPS=$(wildcard src/cmd/linuxkit/*.go) $(wildcard src/cmd/linuxkit/*/*.go) Makefile src/cmd/linuxkit/vendor.conf
-bin/linuxkit: tmp_linuxkit_bin.tar
-	tar xf $<
-	rm $<
-	touch $@
-
-tmp_linuxkit_bin.tar: $(LINUXKIT_DEPS)
-	tar cf - -C src/cmd/linuxkit . | docker run --rm --net=none --log-driver=none -i $(CROSS) $(GO_COMPILE) --package github.com/linuxkit/linuxkit/src/cmd/linuxkit --ldflags "-X github.com/linuxkit/linuxkit/src/cmd/linuxkit/version.GitCommit=$(GIT_COMMIT) -X github.com/linuxkit/linuxkit/src/cmd/linuxkit/version.Version=$(VERSION)" -o bin/linuxkit > $@
+.PHONY: linuxkit
+linuxkit: bin
+	make -C ./src/cmd/linuxkit
 
 .PHONY: test-cross
 test-cross:
-	$(MAKE) clean
-	$(MAKE) -j 3 GOOS=darwin tmp_rtf_bin.tar tmp_mt_bin.tar tmp_linuxkit_bin.tar
-	$(MAKE) clean
-	$(MAKE) -j 3 GOOS=windows tmp_rtf_bin.tar tmp_mt_bin.tar tmp_linuxkit_bin.tar
-	$(MAKE) clean
-	$(MAKE) -j 3 GOOS=linux tmp_rtf_bin.tar tmp_mt_bin.tar tmp_linuxkit_bin.tar
-	$(MAKE) clean
+	make -C ./src/cmd/linuxkit test-cross
 
-LOCAL_LDFLAGS += -X github.com/linuxkit/linuxkit/src/cmd/linuxkit/version.GitCommit=$(GIT_COMMIT) -X github.com/linuxkit/linuxkit/src/cmd/linuxkit/version.Version=$(VERSION)
-LOCAL_TARGET ?= bin/linuxkit
+.PHONY: local local-%
+local:
+	make -C ./src/cmd/linuxkit local
 
-.PHONY: local-check local-build local-test local-static-pie local-static local-dynamic local
-local-check: $(LINUXKIT_DEPS)
-	@echo gofmt... && o=$$(gofmt -s -l $(filter %.go,$(LINUXKIT_DEPS))) && if [ -n "$$o" ] ; then echo $$o ; exit 1 ; fi
-	@echo govet... && go tool vet -printf=false $(filter %.go,$(LINUXKIT_DEPS))
-	@echo golint... && set -e ; for i in $(filter %.go,$(LINUXKIT_DEPS)); do golint $$i ; done
-	@echo ineffassign... && ineffassign  $(filter %.go,$(LINUXKIT_DEPS))
-
-local-build: local-static
-
-local-static-pie: $(LINUXKIT_DEPS) | bin
-	CGO_ENABLED=0 go build -o $(LOCAL_TARGET) --buildmode pie --ldflags "-s -w -extldflags \"-static\" $(LOCAL_LDFLAGS)" github.com/linuxkit/linuxkit/src/cmd/linuxkit
-
-local-static: $(LINUXKIT_DEPS) | bin
-	CGO_ENABLED=0 go build -o $(LOCAL_TARGET) --ldflags "$(LOCAL_LDFLAGS)" github.com/linuxkit/linuxkit/src/cmd/linuxkit
-
-local-dynamic: $(LINUXKIT_DEPS) | bin
-	go build -o $(LOCAL_TARGET) --ldflags "$(LOCAL_LDFLAGS)" github.com/linuxkit/linuxkit/src/cmd/linuxkit
-
-local-test: $(LINUXKIT_DEPS)
-	go test $(shell go list github.com/linuxkit/linuxkit/src/cmd/linuxkit/... | grep -v ^github.com/linuxkit/linuxkit/src/cmd/linuxkit/vendor/)
-
-local: local-check local-build local-test
+local-%:
+	make -C ./src/cmd/linuxkit $@
 
 bin:
 	mkdir -p $@
 
 install:
-	cp -R ./bin/* $(PREFIX)/bin
+	cp -R bin/* $(PREFIX)/bin
+
+sign:
+	codesign --entitlements linuxkit.entitlements --force -s - $(PREFIX)/bin/linuxkit
 
 .PHONY: test
 test:
-	$(MAKE) -C test
-
-.PHONY: collect-artifacts
-collect-artifacts: artifacts/test.img.tar.gz artifacts/test-ltp.img.tar.gz
+	$(MAKE) -C test TEST_SUITE=$(TEST_SUITE) TEST_SHARD=$(TEST_SHARD)
 
 .PHONY: ci ci-tag ci-pr
 ci: test-cross
@@ -123,3 +106,40 @@ ci-pr: test-cross
 .PHONY: clean
 clean:
 	rm -rf bin *.log *-kernel *-cmdline *-state *.img *.iso *.gz *.qcow2 *.vhd *.vmx *.vmdk *.tar *.raw
+
+update-package-tags:
+ifneq ($(LK_RELEASE),)
+	$(eval tags := $(shell cd pkg; make show-tag | cut -d ':' -f1))
+	$(eval image := :$(LK_RELEASE))
+else
+	$(eval tags := $(shell cd pkg; make show-tag))
+	$(eval image := )
+endif
+	for img in $(tags); do \
+		./scripts/update-component-sha.sh --image $${img}$(image); \
+	done
+
+.PHONY: build-targets-all build-targets-linux build-targets-windows build-targets-macos checksum-targets
+
+build-targets-all: build-targets-linux build-targets-windows build-targets-macos
+
+build-targets-linux: bin
+	$(MAKE) GOOS=linux GOARCH=arm64 LOCAL_TARGET=$(CURDIR)/bin/linuxkit-linux-arm64 local-build
+	file bin/linuxkit-linux-arm64
+	$(MAKE) GOOS=linux GOARCH=amd64 LOCAL_TARGET=$(CURDIR)/bin/linuxkit-linux-amd64 local-build
+	file bin/linuxkit-linux-amd64
+	$(MAKE) GOOS=linux GOARCH=s390x LOCAL_TARGET=$(CURDIR)/bin/linuxkit-linux-s390x local-build
+	file bin/linuxkit-linux-s390x
+
+build-targets-windows: bin
+	$(MAKE) GOOS=windows GOARCH=amd64 LOCAL_TARGET=$(CURDIR)/bin/linuxkit-windows-amd64.exe local-build
+	file bin/linuxkit-windows-amd64.exe
+
+build-targets-macos: bin
+	$(MAKE) GOOS=darwin GOARCH=arm64 LOCAL_TARGET=$(CURDIR)/bin/linuxkit-darwin-arm64 local-build
+	file bin/linuxkit-darwin-arm64
+	$(MAKE) GOOS=darwin GOARCH=amd64 LOCAL_TARGET=$(CURDIR)/bin/linuxkit-darwin-amd64 local-build
+	file bin/linuxkit-darwin-amd64
+
+checksum-targets: bin
+	cd bin && openssl sha256 -r linuxkit-* | tr -d '*' > checksums.txt

README.md

@@ -10,12 +10,13 @@ LinuxKit, a toolkit for building custom minimal, immutable Linux distributions.
 - Completely stateless, but persistent storage can be attached
 - Easy tooling, with easy iteration
 - Built with containers, for running containers
+- Designed to create [reproducible builds](./docs/reproducible-builds.md) [WIP]
 - Designed for building and running clustered applications, including but not limited to container orchestration such as Docker or Kubernetes
 - Designed from the experience of building Docker Editions, but redesigned as a general-purpose toolkit
-- Designed to be managed by external tooling, such as [Infrakit](https://github.com/docker/infrakit) or similar tools
+- Designed to be managed by external tooling, such as [Infrakit](https://github.com/docker/infrakit) (renamed to [deploykit](https://github.com/docker/deploykit) which has been archived in 2019) or similar tools
 - Includes a set of longer-term collaborative projects in various stages of development to innovate on kernel and userspace changes, particularly around security
 
-LinuxKit currently supports the `x86_64`, `arm64`, and `s390x` architectures on a variety of platforms, both as virtual machines and baremetal (see [below](#booting-and-testing) for details.
+LinuxKit currently supports the `x86_64`, `arm64`, and `s390x` architectures on a variety of platforms, both as virtual machines and baremetal (see [below](#booting-and-testing) for details).
 
 ## Subprojects
 
@@ -24,6 +25,7 @@ LinuxKit currently supports the `x86_64`, `arm64`, and `s390x` architectures on
 - [linux](https://github.com/linuxkit/linux) A copy of the Linux stable tree with branches LinuxKit kernels.
 - [virtsock](https://github.com/linuxkit/virtsock) A `go` library and test utilities for `virtio` and Hyper-V sockets.
 - [rtf](https://github.com/linuxkit/rtf) A regression test framework used for the LinuxKit CI tests (and other projects).
+- [homebrew](https://github.com/linuxkit/homebrew-linuxkit) Homebrew packages for the `linuxkit` tool.
 
 ## Getting Started
 
@@ -34,7 +36,7 @@ LinuxKit uses the `linuxkit` tool for building, pushing and running VM images.
 Simple build instructions: use `make` to build. This will build the tool in `bin/`. Add this
 to your `PATH` or copy it to somewhere in your `PATH` eg `sudo cp bin/* /usr/local/bin/`. Or you can use `sudo make install`.
 
-If you already have `go` installed you can use `go get -u github.com/linuxkit/linuxkit/src/cmd/linuxkit` to install the `linuxkit` tool.
+If you already have `go` installed you can use `go install github.com/linuxkit/linuxkit/src/cmd/linuxkit@latest` to install the `linuxkit` tool.
 
 On MacOS there is a `brew tap` available. Detailed instructions are at [linuxkit/homebrew-linuxkit](https://github.com/linuxkit/homebrew-linuxkit),
 the short summary is
@@ -43,11 +45,17 @@ brew tap linuxkit/linuxkit
 brew install --HEAD linuxkit
 ```
 
-Build requirements from source:
+Build requirements from source using a container
 - GNU `make`
 - Docker
 - optionally `qemu`
 
+For a local build using `make local`
+- `go`
+- `make`
+- `go get -u golang.org/x/lint/golint`
+- `go get -u github.com/gordonklaus/ineffassign`
+
 ### Building images
 
 Once you have built the tool, use
@@ -55,10 +63,8 @@ Once you have built the tool, use
 ```
 linuxkit build linuxkit.yml
 ```
-to build the example configuration. You can also specify different output formats, eg `linuxkit build -format raw-bios linuxkit.yml` to
-output a raw BIOS bootable disk image, or `linuxkit build -format iso-efi linuxkit.yml` to output an EFI bootable ISO image. See `linuxkit build -help` for more information.
-
-Since `linuxkit build` is built around the [Moby tool](https://github.com/moby/tool) the input yml files are described in the [Moby tool documentation](https://github.com/moby/tool/blob/master/docs/yaml.md).
+to build the example configuration. You can also specify different output formats, eg `linuxkit build --format raw-bios linuxkit.yml` to
+output a raw BIOS bootable disk image, or `linuxkit build --format iso-efi linuxkit.yml` to output an EFI bootable ISO image. See `linuxkit build -help` for more information.
 
 ### Booting and Testing
 
@@ -69,6 +75,7 @@ for example VMWare.  See `linuxkit run --help`.
 
 Currently supported platforms are:
 - Local hypervisors
+  - [Virtualization.Framework (macOS)](docs/platform-virtualization-framework.md) `[x86_64, arm64]`
   - [HyperKit (macOS)](docs/platform-hyperkit.md) `[x86_64]`
   - [Hyper-V (Windows)](docs/platform-hyperv.md) `[x86_64]`
   - [qemu (macOS, Linux, Windows)](docs/platform-qemu.md) `[x86_64, arm64, s390x]`
@@ -78,8 +85,9 @@ Currently supported platforms are:
   - [Google Cloud](docs/platform-gcp.md) `[x86_64]`
   - [Microsoft Azure](docs/platform-azure.md) `[x86_64]`
   - [OpenStack](docs/platform-openstack.md) `[x86_64]`
+  - [Scaleway](docs/platform-scaleway.md) `[x86_64]`
 - Baremetal:
-  - [packet.net](docs/platform-packet.md) `[x86_64, arm64]`
+  - [deploy.equinix.com](docs/platform-equinixmetal.md) `[x86_64, arm64]`
   - [Raspberry Pi Model 3b](docs/platform-rpi3.md)  `[arm64]`
 
 
@@ -117,7 +125,7 @@ To customise, copy or modify the [`linuxkit.yml`](linuxkit.yml) to your own `fil
 generate its specified output. You can run the output with `linuxkit run file`.
 
 The yaml file specifies a kernel and base init system, a set of containers that are built into the generated image and started at boot time. You can specify the type
-of artifact to build with the `moby` tool eg `linuxkit build -format vhd linuxkit.yml`.
+of artifact to build eg `linuxkit build -format vhd linuxkit.yml`.
 
 If you want to build your own packages, see this [document](docs/packages.md).
 
@@ -131,7 +139,7 @@ The yaml format specifies the image to be built:
 - `services` is the system services, which normally run for the whole time the system is up
 - `files` are additional files to add to the image
 
-For a more detailed overview of the options see [yaml documentation](https://github.com/moby/tool/blob/master/docs/yaml.md)
+For a more detailed overview of the options see [yaml documentation](docs/yaml.md)
 
 ## Architecture and security
 
@@ -156,7 +164,11 @@ This is an open project without fixed judgements, open to the community to set t
 
 ## Development reports
 
-There are weekly [development reports](reports/) summarizing work carried out in the week.
+There are monthly [development reports](reports/) summarising the work carried out each month.
+
+## Adopters
+
+We maintain an incomplete list of [adopters](ADOPTERS.md). Please open a PR if you are using LinuxKit in production or in your project, or both.
 
 ## FAQ
 

contrib/crosvm/Dockerfile

@@ -1,7 +1,7 @@
-FROM rust:1.25.0-stretch
+FROM rust:1.30.0-stretch
 
 ENV CROSVM_REPO=https://chromium.googlesource.com/chromiumos/platform/crosvm
-ENV CROSVM_COMMIT=7a7268faf0a43c79b6a4520f5c2f35c3e0233932
+ENV CROSVM_COMMIT=c527c1a7e8136dae1e8ae728dfd9932bf3967e7e
 ENV MINIJAIL_REPO=https://android.googlesource.com/platform/external/minijail
 ENV MINIJAIL_COMMIT=d45fc420bb8fd9d1fc9297174f3c344db8c20bbd
 

contrib/crosvm/README.md

@@ -25,56 +25,30 @@ You may also have to create an empty directory `/var/empty`.
 ## Use with LinuxKit images
 
 You can build a LinuxKit image suitable for `crosvm` with the
-`kernel+squashfs` build format. For example, using this LinuxKit
-YAML file (`minimal.yml`):
-
-```
-kernel:
-  image: linuxkit/kernel:4.9.91
-  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-services:
-  - name: getty
-    image: linuxkit/getty:v0.4
-    env:
-      - INSECURE=true
-trust:
-  org:
-    - linuxkit
-```
-
-run:
+`kernel+squashfs` build format. For example, using `minimal.yml` from
+the `./examples` directory, run (but also see the known issues):
 
 ```sh
-linuxkit build -output kernel+squashfs minimal.yml
+linuxkit build -format kernel+squashfs -decompress-kernel minimal.yml
 ```
 
-The kernel this produces (`minimal-kernel`) needs to be converted as
-`crosvm` does not grok `bzImage`s. You can convert the LinuxKit kernel
-image with
-[extract-vmlinux](https://raw.githubusercontent.com/torvalds/linux/master/scripts/extract-vmlinux):
-
-```sh
-extract-vmlinux minimal-kernel > minimal-vmlinux
-```
+The `-vmlinux` switch is needed since `crosvm` does not grok
+compressed linux kernel images.
 
 Then you can run `crosvm`:
 ```sh
-./crosvm run --seccomp-policy-dir=./seccomp/x86_64 \
+crosvm run --disable-sandbox \
     --root ./minimal-squashfs.img \
     --mem 2048 \
-    --multiprocess \
     --socket ./linuxkit-socket \
-    minimal-vmlinux
+    minimal-kernel
 ```
 
 ## Known issues
 
 - With 4.14.x, a `BUG_ON()` is hit in `drivers/base/driver.c`. 4.9.x
   kernels seem to work.
+- With the latest version, I don't seem to get a interactive console.
 - Networking does not yet work, so don't include a `onboot` `dhcpd` service.
 - `poweroff` from the command line does not work (crosvm does not seem
   to support ACPI). So to stop a VM you can use the control socket

contrib/foreign-kernels/Dockerfile.deb

@@ -1,4 +1,4 @@
-FROM alpine:3.7 AS extract
+FROM alpine:3.8 AS extract
 
 ARG DEB_URLS
 

contrib/foreign-kernels/Dockerfile.rpm

@@ -1,4 +1,4 @@
-FROM alpine:3.7 AS extract
+FROM alpine:3.8 AS extract
 
 ARG RPM_URLS
 

contrib/open-vm-tools/README.md

@@ -0,0 +1,10 @@
+# open-vm-tools
+This should allow end-users to gracefully reboot or shutdown Kubernetes nodes (incuding control planes) running on vSphere Hypervisor.
+
+Furthermore, it is also mandatory to have `open-vm-tools` installed on your Kubernetes nodes to use vSphere Cloud Provider (i.e. determinte virtual machine's FQDN).
+
+## Remarks:
+- `spec.template.spec.hostNetwork: true`: correctly report node IP address; required
+- `spec.template.spec.hostPID: true`: send the right signal to node, instead of killing the container itself; required
+- `spec.template.spec.priorityClassName: system-cluster-critical`: critical to a fully functional cluster
+- `spec.template.spec.securityContext.privileged: true`: gain more privileges than its parent process; required

contrib/open-vm-tools/open-vm-tools-ds.yaml

@@ -0,0 +1,45 @@
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  labels:
+    app: open-vm-tools
+  name: open-vm-tools
+  namespace: kube-system
+spec:
+  selector:
+    matchLabels:
+      app: open-vm-tools
+  template:
+    metadata:
+      labels:
+        app: open-vm-tools
+    spec:
+      hostNetwork: true
+      hostPID: true
+      priorityClassName: system-cluster-critical
+      tolerations:
+      - key: node.cloudprovider.kubernetes.io/uninitialized
+        value: "true"
+        effect: NoSchedule
+      - key: node-role.kubernetes.io/master
+      - key: node-role.kubernetes.io/master
+        operator: Exists
+        effect: NoSchedule
+      - key: node-role.kubernetes.io/control-plane
+      - key: node-role.kubernetes.io/control-plane
+        operator: Exists
+        effect: NoSchedule
+      containers:
+      - image: linuxkit/open-vm-tools:728ddf726474178eea97604c0baeabd52edab7e9
+        name: open-vm-tools
+        resources:
+          requests:
+            memory: "5Mi"
+            cpu: "100m"
+          limits:
+            memory: "25Mi"
+            cpu: "500m"
+        securityContext:
+          privileged: true
+      dnsPolicy: ClusterFirst
+      restartPolicy: Always

docs/alpine-base-update.md

@@ -0,0 +1,238 @@
+# Updating Alpine Base
+
+This document describes the steps to update the `linuxkit/alpine` image.
+This image is at the base of all other linuxkit images.
+It is built out of the directory `tools/alpine/`.
+
+While you do not need to update every downstream image _immediately_ when you update
+this image, you do need to be aware that changes to this image will affect the
+downstream images when it is next adopted. Those downstream images should be updated
+as soon as possible after updating `linuxkit/alpine`.
+
+When you make a linuxkit release, you _must_ update all of the downstream images.
+See [releasing.md](./releasing.md) for the release process.
+
+## Pre-requisites
+
+Updating `linuxkit/alpine` can be done by any maintainer. Maintainers need to have
+access to build machines for all architectures support by LinuxKit.
+
+## Process
+
+At a high-level, we are going to do the following:
+
+1. Preparatory steps
+1. Create a new branch
+1. Make our desired changes to `tools/alpine` and commit them
+1. Build and push out our alpine changes, and commit the `versions` files
+1. Update all affected downstream changes and commit them: `tools/`, `test/pkg`, `pkg`, `test/`, `examples/`
+1. Push out all affected downstream changes: `tools/`, `test/pkg`, `pkg`, `test/`, `examples/`
+
+For each of the affected downstream changes, we could update and then push, then move to the next. However,
+since the push out can be slow and require retries, we try to make all of the changes first, and then push them out.
+
+### Preparation
+
+As a starting point you have to be on the update to date master branch
+and be in the root directory of your local git clone. You should also
+have the same setup on all build machines used.
+
+To make the steps below cut-and-pastable, define the following
+environment variables:
+
+```sh
+LK_ROOT=$(pwd)
+LK_REMOTE=origin         # or whatever your personal remote is
+LK_BRANCH=alpine-update  # or whatever the name of the branch on which you are working is
+```
+
+Note that if you are cutting a release, the `LK_BRANCH` may have a release-type name, e.g. `rel_v0.4`.
+
+Make sure that you have the latest version of the `linuxkit`
+utility in the path. Alternatively, you may wish to compile the latest version from
+master.
+
+### Create a new branch
+
+On one of the build machines (preferably the `x86_64` machine), create
+the branch:
+
+```sh
+git checkout -b $LK_BRANCH
+```
+
+### Update `linuxkit/alpine`
+
+You must perform the arch-specific image builds, pushes and updates on each
+architecture first - these can be done in parallel, if you choose. When done,
+you then copy the updated `versions.<arch>` to one place, commit them, and
+push the manifest.
+
+#### Make alpine changes
+
+Make any changes in `tools/alpine` that you desire, then commit them.
+In the below, change the commit message to something meaningful to the change you are making.
+
+```sh
+cd tools/alpine
+# make changes
+git commit -s -a -m "Update linuxkit/alpine"
+git push origin $LK_BRANCH
+```
+
+#### Build and Push Alpine Per-Architecture
+
+On each supported platform, build and update `linuxkit/alpine`, which will update the `versions.<arch>`
+file.:
+
+```sh
+git fetch
+git checkout $LK_BRANCH
+cd $LK_ROOT/tools/alpine
+make push
+```
+
+Repeat on each platform.
+
+#### Commit Changed Versions Files
+
+When all of the platforms are done, copy the changed `versions.<arch>` from each platform to one place, commit and push.
+In the below, replace `linuxkit-arch` with each build machine's name:
+
+```sh
+# one of these will not be necessary, as you will likely be executing it on one of these machines
+scp linuxkit-s390x:$LK_ROOT/tools/alpine/versions.s390x $LK_ROOT/tools/alpine/versions.s390x
+scp linuxkit-aarch64:$LK_ROOT/tools/alpine/versions.aarch64 $LK_ROOT/tools/alpine/versions.aarch64
+scp linuxkit-x86_64:$LK_ROOT/tools/alpine/versions.x86_64 $LK_ROOT/tools/alpine/versions.x86_64
+git commit -a -s -m "tools/alpine: Update to latest"
+git push $LK_REMOTE $LK_BRANCH
+```
+
+#### Update and Push Multi-Arch Index
+
+Push out the multi-arch index:
+
+```sh
+make push-manifest
+```
+
+Stash the tag of the alpine base image in an environment variable:
+
+```sh
+LK_ALPINE=$(make show-tag)
+```
+
+### Update affected downstream packages 
+
+This section describes all of the steps. Below follows a straight copyable list of steps to take,
+following which is an explanation of each one.
+
+```sh
+# Update tools packages
+cd $LK_ROOT/tools
+$LK_ROOT/scripts/update-component-sha.sh --image $LK_ALPINE
+git checkout grub-dev/Dockerfile
+git checkout mkimage-rpi3/Dockerfile
+git commit -a -s -m "tools: Update to the latest linuxkit/alpine"
+
+# Update tools dependencies
+cd $LK_ROOT
+for img in $(cd tools; make show-tag); do
+    $LK_ROOT/scripts/update-component-sha.sh --image $img
+done
+git commit -a -s -m "Update use of tools to latest"
+
+# Update test packages
+cd $LK_ROOT/test/pkg
+$LK_ROOT/scripts/update-component-sha.sh --image $LK_ALPINE
+git commit -a -s -m "tests: Update packages to the latest linuxkit/alpine"
+
+# Update test packages dependencies
+cd $LK_ROOT
+for img in $(cd test/pkg; make show-tag); do
+    $LK_ROOT/scripts/update-component-sha.sh --image $img
+done
+git commit -a -s -m "Update use of test packages to latest"
+
+# Update test cases to latest linuxkit/alpine
+cd $LK_ROOT/test/cases
+$LK_ROOT/scripts/update-component-sha.sh --image $LK_ALPINE
+git commit -a -s -m "tests: Update tests cases to the latest linuxkit/alpine"
+
+# Update packages to latest linuxkit/alpine
+cd $LK_ROOT/pkg
+$LK_ROOT/scripts/update-component-sha.sh --image $LK_ALPINE
+git commit -a -s -m "pkgs: Update packages to the latest linuxkit/alpine"
+
+# update package tags - may want to include the release in it if set
+cd $LK_ROOT
+make update-package-tags
+MSG=""
+[ -n "$LK_RELEASE" ] && MSG="to $LK_RELEASE"
+git commit -a -s -m "Update package tags $MSG"
+
+git push $LK_REMOTE $LK_BRANCH
+```
+
+#### Update tools packages
+
+On your primary build machine, update the other tools packages.
+
+Note, the `git checkout` reverts the changes made by
+`update-component-sha.sh` to files which are accidentally updated.
+Important is the `git checkout` of some sensitive packages that only can be built with
+specific older versions of upstream packages:
+
+* `grub-dev`
+* `mkimage-rpi3`
+
+Only update those if you know what you are doing with them.
+
+Then we update any dependencies of these tools.
+
+#### Update test packages
+
+Next, we update the test packages to the updated alpine base.
+
+Next, we update the use of test packages to latest.
+
+Some tests also use `linuxkit/alpine`, so we update them as well.
+
+### Update packages
+
+Next, we update the LinuxKit packages. This is really the core of the
+release. The other steps above are just there to ensure consistency
+across packages.
+
+#### External Tools
+
+Most of the packages are build from `linuxkit/alpine` and source code
+in the `linuxkit` repository, but some packages wrap external
+tools. When updating all packages, and especially during the time of a release,
+is a good opportunity to check if there have been updates. Specifically:
+
+- `pkg/cadvisor`: Check for [new releases](https://github.com/google/cadvisor/releases).
+- `pkg/firmware` and `pkg/firmware-all`: Use latest commit from [here](https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git).
+- `pkg/node_exporter`: Check for [new releases](https://github.com/prometheus/node_exporter/releases).
+- Check [docker hub](https://hub.docker.com/r/library/docker/tags/) for the latest `dind` tags. and update `examples/docker.yml`, `examples/docker-for-mac.yml`, `examples/cadvisor.yml`, and `test/cases/030_security/000_docker-bench/test.yml` if necessary.
+
+This is at your discretion.
+
+### Build and push affected downstream packages
+
+<ul>Note</ul>: All of the `make push` and `make forcepush` in this section use `linuxkit pkg push`, which will build for all architectures and push
+the images out. See [Build Platforms](./packages.md#Build_Platforms).
+
+```sh
+# build and push out the tools packages
+cd $LK_ROOT/tools
+make forcepush
+
+# Build and push out test packages
+cd $LK_ROOT/test/pkg
+make push
+
+# build and push out the packages
+cd $LK_ROOT/pkg
+make push
+```

docs/cmdline.md

@@ -0,0 +1,19 @@
+# Kernel command-line options
+
+The kernel command-line is a string of text that the kernel parses as it is starting up. It is passed by the boot loader
+to the kernel and specifies parameters that the kernel uses to configure the system. The command-line is a list of command-line
+options separated by spaces. The options are parsed by the kernel and can be used to enable or disable certain features.
+
+LinuxKit passes all command-line options to the kernel, which uses them in the usual way.
+
+There are several options that can be used to control the behaviour of linuxkit itself, or specifically packages
+within linuxkit. Unless standard Linux options exist, these all are prefaced with `linuxkit.`.
+
+| Option | Description |
+|---|---|
+| `linuxkit.unified_cgroup_hierarchy=0` | Start up cgroups v1. If not present or set to 1, default to cgroups v1. |
+| `linuxkit.runc_debug=1` | Start runc for `onboot` and `onshutdown` containers to run with `--debug`, and add extra logging messages for each stage of starting those containers. If not present or set to 0, default to usual mode. |
+| `linuxkit.runc_console=1` | Send logs for runc for `onboot` and `onshutdown` containers, as well as the output of the containers themselves, to the console, instead of the normal output to logfiles. If not present or set to 0, default to usual mode. |
+
+It often is useful to combine both of the `linuxkit.runc_debug` and `linuxkit.runc_console` options to get the most
+information about what is happening with `onboot` containers.

docs/developer-setup.md

@@ -0,0 +1,81 @@
+# Build Platforms
+
+This document describes how to install and maintain a LinuxKit development platform. It will grow over time.
+
+The LinuxKit team also maintains several Linux-based build platforms. These are donated by Equinix Metal (arm64) and IBM (s390x).
+
+## Platform-Specific Installation
+
+### arm64 and amd64
+
+The `amd64` and `arm64` platforms are fully supported by most OS vendors and Docker. Just upgrade to the latest OS and install the latest Docker using the
+packaging tools. As of this writing, that is:
+
+* Ubuntu/Debian with `apt`
+* RHEL/CentOS/Fedora with `yum`. For any of these, use the CentOS 7/8 packages as released by Docker.
+
+Docker does not recommend that you using the packages released by the OS vendors, as those tend to be out of date. Follow the instructions
+[from Docker](https://docs.docker.com/engine/install/).
+
+### s390x
+
+The s390x has modern versions of most OSes, including RHEL and Ubuntu, but does not have recent versions of docker, neither as
+`apt` packages for Ubuntu, nor as static downloads. In any case, these static downloads mostly are replicas.
+
+This section describes how to install modern versions of Docker on these platforms.
+
+#### RHEL
+
+RHEL 7 on s390x only has releases from Docker. Follow the instructions from Docker to install. The rpm packages for RHEL are available at
+https://download.docker.com/linux/rhel/
+
+#### Ubuntu
+
+Docker does not release packages for Ubuntu on s390x. The most recent release was for Ubuntu 18.04 Bionic, with Docker version 18.06.3.
+This is quite old, and does not support modern capabilities, e.g. buildkit.
+
+To install a more modern version:
+
+1. Upgrade any dependent apt packages `apt upgrade`
+1. Upgrade the operating system to your desired version `do-release-upgrade -d`. Note that you can set which versions to suggest via changing `/etc/update-manager/release-upgrades`
+1. Download the necessary rpms (yes, rpms) from the Docker RHEL7 site. These are available [here](https://download.docker.com/linux/rhel/7/s390x/stable/Packages/). You need the following packages:
+   * `containerd.io-*.rpm`
+   * `docker-ce-*.rpm`
+   * `docker-ce-cli-*.rpm`
+1. Install alien: `apt install alien`
+1. Convert each package to a dpkg `alien --scripts <source-rpm-file.rpm>`
+1. Install each package with `dpkg -i <source-dpkg>.dpkg`. Dependency management is not great, so we recommend installing them in order:
+   1. `containerd.io`
+   1. `docker-ce`
+   1. `docker-ce-cli`
+1. Install devmapper `apt install libdevmapper-dev`
+1. Check the missing version of libdevmapper, if any, with `ldd /usr/bin/dockerd`. In our example, it needs `libdevmapper.so.1.02`
+1. Ensure that the library can be found where needed via `cd /lib/s390x-linux-gnu/ && ln -s $(ls -1 libdevmapper.so.*) libdevmapper.so.1.02`
+1. Check again that dockerd is ok: `ldd /usr/bin/dockerd`
+1. Start docker `system ctl restart docker`
+1. Check that everything works:
+   * `docker version`
+   * `docker run --rm hello-world`
+
+## Common Notes
+
+On all platforms, if you want to run tests, you will need:
+
+* `jq`
+* `expect`
+* `qemu-kvm`
+
+These should be installed using your normal platform package installation, e.g. `apt install -y jq expect qemu-kvm`.
+
+You also will need `rtf`, which can be installed with `make bin/rtf && make install`.
+
+For pushing our kernels, you will need [manifest-tool](http://github.com/estesp/manifest-tool), which can be installed with
+`make bin/manifest-tool && make install`.
+
+Finally, to enable your regular user to run the tools, we recommend:
+
+```
+usermod -aG docker $USER
+usermod -aG kvm $USER
+usermod -aG sudo $USER
+```

docs/encrypted-disk.md

@@ -0,0 +1,86 @@
+# Device encryption with dm-crypt
+
+In the packages section you can find an image to setup dm-crypt encrypted devices in [linuxkit](https://github.com/linuxkit/linuxkit)-generated images.
+
+## Usage
+
+The setup is a one time step during boot:
+
+```yaml
+onboot:
+  - name: dm-crypt
+    image: linuxkit/dm-crypt:<hash>
+    command: ["/usr/bin/crypto", "dm_crypt_name", "/dev/sda1"]
+  - name: mount
+    image: linuxkit/mount:<hash>
+    command: ["/usr/bin/mountie", "/dev/mapper/dm_crypt_name", "/var/secure_storage"]
+files:
+  - path: etc/dm-crypt/key
+    contents: "abcdefghijklmnopqrstuvwxyz123456"
+```
+
+The above will map `/dev/sda1` as an encrypted device under `/dev/mapper/dm_crypt_name` and mount it under `/var/secure_storage`
+
+The `dm-crypt` container by default bind-mounts `/dev:/dev` and `/etc/dm-crypt:/etc/dm-crypt`. It expects the encryption key to be present in the file `/etc/dm-crypt/key`. You can pass an alternative location as encryption key which can be either a file path relative to `/etc/dm-crypt` or an absolute path.
+
+Providing an alternative encryption key file name:
+
+```yaml
+onboot:
+  - name: dm-crypt
+    image: linuxkit/dm-crypt:<hash>
+    command: ["/usr/bin/crypto", "-k", "some_other_key", "dm_crypt_name", "/dev/sda1"]
+  - name: mount
+    image: linuxkit/mount:<hash>
+    command: ["/usr/bin/mountie", "/dev/mapper/dm_crypt_name", "/var/secure_storage"]
+files:
+  - path: etc/dm-crypt/some_other_key
+    contents: "abcdefghijklmnopqrstuvwxyz123456"
+```
+
+Providing an alternative encryption key file name as absolute path:
+
+```yaml
+onboot:
+  - name: dm-crypt
+    image: linuxkit/dm-crypt:<hash>
+    command: ["/usr/bin/crypto", "-k", "/some/other/key", "dm_crypt_name", "/dev/sda1"]
+    binds:
+      - /dev:/dev
+      - /etc/dm-crypt/some_other_key:/some/other/key
+  - name: mount
+    image: linuxkit/mount:<hash>
+    command: ["/usr/bin/mountie", "/dev/mapper/dm_crypt_name", "/var/secure_storage"]
+files:
+  - path: etc/dm-crypt/some_other_key
+    contents: "abcdefghijklmnopqrstuvwxyz123456"
+```
+
+Note that you have to also map `/dev:/dev` explicitly if you override the default bind-mounts.
+
+The `dm-crypt` container
+
+* Will create an `ext4` file system on the encrypted device if none is present.
+  * It will also initialize the encrypted device by filling it from `/dev/zero` prior to creating the filesystem. Which means if the device is being setup for the first time it might take a bit longer.
+* Uses the `aes-cbc-essiv:sha256` cipher (it's explicitly specified in case the default ever changes)
+  * Consequently the encryption key is expected to be 32 bytes long, a random one can be created via
+    ```shell
+    dd if=/dev/urandom of=dm-crypt.key bs=32 count=1
+    ```
+    If you see the error `Cannot read requested amount of data.` next to the log message `Creating dm-crypt mapping for ...` then this means your keyfile doesn't contain enough data.
+
+### Examples
+
+There are two examples in the `examples/` folder:
+
+1. `dm-crypt.yml` - formats an external disk and mounts it encrypted.
+2. `dm-crypt-loop.yml` - mounts an encrypted loop device backed by a regular file sitting on an external disk
+
+### Options
+
+|Option|Default|Required|Notes|
+|---|---|---|---|
+|`-k` or `--key`|`key`|No|Encryption key file name. Must be either relative to `/etc/dm-crypt` or an absolute file path.|
+|`-l` or `--luks`||No|Use LUKS format for encryption|
+|`<dm_name>`||**Yes**|The device-mapper device name to use. The device will be mapped under `/dev/mapper/<dm_name>`|
+|`<device>`||**Yes**|Device to encrypt.|

docs/external-disk.md

@@ -7,7 +7,8 @@
 ## Make Disk Available
 In order to make the disk available, you need to tell `linuxkit` where the disk file or block device is.
 
-All local `linuxkit run` methods (currently `hyperkit`, `qemu`, and `vmware`) take a `-disk` argument:
+All local `linuxkit run` methods (currently `hyperkit`, `qemu`, `virtualization.framework` and `vmware`)
+take a `-disk` argument:
 
 * `-disk path,size=100M,format=qcow2`. For size the default is in GB but an `M` can be appended to specify sizes in MB. The format can be omitted for the platform default, and is only useful on `qemu` at present.
 
@@ -52,9 +53,17 @@ onboot:
     command: ["/usr/bin/format", "-force", "-type", "xfs", "-label", "DATA", "-verbose", "/dev/vda"]
 ```
 
+```
+onboot:
+  - name: format
+    image: linuxkit/format:<hash>
+    command: ["/usr/bin/format", "-type", "ext4", "-partition", "gpt", "/dev/vda"]
+```
+
 - `-force` can be used to force the partition to be cleared and recreated (if applicable), and the recreated partition formatted. This option would be used to re-init the partition on every boot, rather than persisting the partition between boots.
 - `-label` can be used to give the disk a label
 - `-type` can be used to specify the type. This is `ext4` by default but `btrfs` and `xfs` are also supported
+- `-partition` can be used to specify the partition table type. This is `dos` by default but `gpt` is also supported
 - `-verbose` enables verbose logging, which can be used to troubleshoot device auto-detection and (re-)partitioning
 - The final (optional) argument specifies the device name
 

docs/faq.md

@@ -6,7 +6,7 @@ Please open an issue if you want to add a question here.
 
 LinuxKit does not require being installed on a disk, it is often run from an ISO, PXE or other
 such means, so it does not require an on disk upgrade method such as the ChromeOS code that
-is often used. It would definitely be possible to use that type of upgrade method if the 
+is often used. It would definitely be possible to use that type of upgrade method if the
 system is installed, and it would be useful to support this for that use case, and an
 updater container to control this for people who want to use this.
 
@@ -30,3 +30,95 @@ of dependencies and functionality that we do not need. At present we are using t
 `init` process, and a small set of minimal scripts, but we expect to replace that with a small
 standalone `init` process and a small piece of code to bring up the system containers where the
 real work takes place.
+
+## Console not displaying init or containerd output at boot
+
+If you're not seeing `containerd` logs in the console during boot, make sure that your kernel `cmdline` configuration doesn't list multiple consoles.
+
+`init` and other processes like `containerd` will use the last defined console in the kernel `cmdline`. When using `qemu`, to see the console you need to list `ttyS0` as the last console to properly see the output.
+
+## Enabling and controlling containerd logs
+
+On startup, linuxkit looks for and parses a file `/etc/containerd/runtime-config.toml`. If it exists, the content is used to configure containerd runtime.
+
+Sample config is below:
+
+```toml
+cliopts="--log-level debug"
+stderr="/var/log/containerd.out.log"
+stdout="stdout"
+```
+
+The options are as follows:
+
+* `cliopts`: options to pass to the containerd command-line as is.
+* `stderr`: where to send stderr from containerd. If blank, it sends it to the default stderr, which is the console.
+* `stdout`: where to send stdout from containerd. If blank, it sends it to the default stdout, which is the console. containerd normally does not have any stdout.
+
+The `stderr` and `stdout` options can take exactly one of the following options:
+
+* `stderr` - send to stderr
+* `stdout` - send to stdout
+* any absolute path (beginning with `/`) - send to that file. If the file exists, append to it; if not, create it and append to it.
+
+Thus, to enable
+a higher log level, for example `debug`, create a file whose contents are `--log-level debug` and place it on the image:
+
+```yml
+files:
+  - path: /etc/containerd/runtime-config.toml
+    source: "/path/to/runtime-config.toml"
+    mode: "0644"
+```
+
+Note that the package that parses the `cliopts` splits on _all_ whitespace. It does not, as of this writing, support shell-like parsing, so the following will work:
+
+```
+--log-level debug --arg abcd
+```
+
+while the following will not:
+
+```
+--log-level debug --arg 'abcd def'
+```
+
+## Troubleshooting containers
+
+Linuxkit runs all services in a specific `containerd` namespace called `services.linuxkit`. To list all the defined containers:
+
+```sh
+(ns: getty) linuxkit-befde23bc535:~# ctr -n services.linuxkit container ls
+CONTAINER               IMAGE    RUNTIME
+getty                   -        io.containerd.runtime.v1.linux
+```
+
+To list all running containers and their status:
+
+```sh
+(ns: getty) linuxkit-befde23bc535:~# ctr -n services.linuxkit task ls
+TASK                    PID    STATUS
+getty                   661    RUNNING
+```
+
+To list all processes running in a container:
+
+```sh
+(ns: getty) linuxkit-befde23bc535:/containers/services/getty# ctr -n services.linuxkit task ps getty
+PID     INFO
+661     &ProcessDetails{ExecID:getty,}
+677     -
+685     -
+686     -
+687     -
+1237    -
+```
+
+To attach a shell to a running container:
+
+```sh
+(ns: getty) linuxkit-befde23bc535:/containers/services/getty# ctr -n services.linuxkit tasks exec --tty --exec-id sh sshd /bin/ash -l
+(ns: sshd) linuxkit-befde23bc535:/#
+```
+
+Containers are defined as OCI bundles in `/containers`.

docs/image-cache.md

@@ -0,0 +1,61 @@
+# Image Caching
+
+linuxkit builds each runtime OS image from a combination of Docker images.
+These images are pulled from a registry and cached locally.
+
+linuxkit does not use the docker image cache to store these images. This is
+for two key reasons.
+
+First, docker does not provide support for different architecture versions. For
+example, if you want to pull down `docker.io/library/alpine:3.13` by manifest,
+with its signature, but get the `arm64` version while you are on an `amd64` device,
+it is not supported.
+
+Second, and more importantly, this requires a running docker daemon. Since the
+very essence of linuxkit is removing daemons and operating systems where unnecessary,
+just laying down bits in a file, removing docker from the image build process
+is valuable. It also simplifies many use cases, like CI, where a docker daemon
+may be unavailable.
+
+## How LinuxKit Caches Images
+
+LinuxKit pulls images down from a registry and stores them in a local cache.
+It stores the root manifest or index of the image, the manifest, and all of the layers
+for the requested architecture. It does not pull down layers, manifest or config
+for all available architectures, only the requested one. If none is requested, it
+defaults to the architecture on which you are running.
+
+By default, LinuxKit caches images in `~/.linuxkit/cache/`. It can be changed
+via a command-line option. The structure of the cache directory matches the
+[OCI spec for image layout](http://github.com/opencontainers/image-spec/blob/master/image-layout.md).
+
+Image names are kept in `index.json` in the [annotation](https://github.com/opencontainers/image-spec/blob/master/annotations.md) `org.opencontainers.image.ref.name`. For example"
+
+```json
+{
+  "schemaVersion": 2,
+  "manifests": [
+    {
+      "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
+      "size": 1638,
+      "digest": "sha256:9a839e63dad54c3a6d1834e29692c8492d93f90c59c978c1ed79109ea4fb9a54",
+      "annotations": {
+        "org.opencontainers.image.ref.name": "docker.io/library/alpine:3.13"
+      }
+    }
+  ]
+}
+```
+
+## How LinuxKit Uses the Cache and Registry
+
+For each image that linuxkit needs to read, it does the following. Note that if the `--pull` option
+is provided, it always will pull, independent of what is in the cache.
+
+1. Check in the cache for the image name in the cache `index.json`. If it does not find it, pull it down and store it in cache.
+1. Read the root hash from `index.json`.
+1. Find the root blob in the `blobs/` directory via the hash and read it.
+1. Proceed to read the manifest, config and layers.
+
+The read process is smart enough to check each blob in the local cache before downloading
+it from a registry.

docs/kernel-bcc.md

@@ -0,0 +1,31 @@
+# Using the bcc utility with LinuxKit
+
+The `bcc` utility is a standard Linux tool to access performance
+counters, trace events and access various other kernel internals for
+performance analysis.
+
+The `bcc` utility needs to matched be with the kernel. For recent
+kernel build, LinuxKit provides a `linuxkit/kernel-bcc` package with
+a matching tag for each kernel under `linuxkit/kernel`.
+
+The preferred way of using the `linuxkit/kernel-bcc` package is to
+add it to the `init` section. This adds `/usr/share/bcc` to the
+  systems' root filesystem. From there it can be
+  - bind mounted into your container
+  - accessed via `/proc/1/root/usr/share/bcc/tools` from with in the `getty`
+    or `ssh` container.
+  - accessed via a nsenter of `/bin/ash` of proc 1.
+
+If you want to use `bcc` you may also want to remove the `sysctl`
+container, or alternatively, disable the kernel pointer restriction it
+enables by default:
+
+```
+echo 0 > /proc/sys/kernel/kptr_restrict
+```
+
+Now, `bcc` is ready to use. The LinuxKit `bcc` package contains
+the `bcc` binary, example and tool scripts, and kernel headers for the
+associated kernel build.
+
+

docs/kernels.md

@@ -10,17 +10,51 @@ The LinuxKit kernels are based on the latest stable releases and are
 updated frequently to include bug and security fixes.  For some
 kernels we do carry additional patches, which are mostly back-ported
 fixes from newer kernels. The full kernel source with patches can be
-found on [github](https://github.com/linuxkit/linux). Each kernel
-image is tagged with the full kernel version (e.g.,
-`linuxkit/kernel:4.9.33`) and with the full kernel version plus the
-hash of the files it was created from (git tree hash of the `./kernel`
-directory). For selected kernels (mostly the LTS kernels and latest
-stable kernels) we also compile/push kernels with additional debugging
-enabled. The hub images for these kernels have the `-dbg` suffix in
-the tag. For some kernels, we also provide matching packages
-containing the `perf` utility for debugging and performance tracing.
-The perf package is called `kernel-perf` and is tagged the same way as
-the kernel packages.
+found on [github](https://github.com/linuxkit/linux).
+
+## Kernel Image Naming and Tags
+
+We publish the following kernel images:
+
+* primary kernel
+* debug kernel
+* tools for the specific kernel build - bcc and perf
+* builder image for the specific kernel build, useful for compiling compatible kernel modules
+
+### Primary Kernel Images
+
+Each kernel image is tagged with:
+
+* the full kernel version, e.g. `linuxkit/kernel:6.6.13`. This is a multi-arch index, and should be used whenever possible.
+* the full kernel version plus hash of the files it was created from (git tree hash of the `./kernel` directory), e.g. `6.6.13-c0d96951e9892a7447a8e7965d2d6bd7e621c3fd`. This is a multi-arch index.
+* the full kernel version plus architecture, e.g. `linuxkit/kernel:6.6.13-amd64` or `linuxkit/kernel:6.6.13-arm64`. Each of these is architecture specific.
+* the full kernel version plus hash of the files it was created from (git tree hash of the `./kernel` directory) plus architecture, e.g. `6.6.13-c0d96951e9892a7447a8e7965d2d6bd7e621c3fd-arm64`.
+
+### Debug Kernel Images
+
+With each kernel image, we also publish kernels with additional debugging enabled.
+These have the same image name and the same tags as the primary kernel, with the `-dbg`
+suffix added immediately after the version. E.g.
+
+* `linuxkit/kernel:6.6.13-dbg`
+* `linuxkit/kernel:6.6.13-dbg-c0d96951e9892a7447a8e7965d2d6bd7e621c3fd`
+* `linuxkit/kernel:6.6.13-dbg-amd64`
+* `linuxkit/kernel:6.6.13-dbg-c0d96951e9892a7447a8e7965d2d6bd7e621c3fd-amd64`
+
+### Tools
+
+With each kernel image, we also publish images with various tools. As of this writing,
+those tools are `perf` and `bcc`.
+
+The tools images are named `linuxkit/kernel-<tool>`, followed by the same tags as the
+primary kernel. For example:
+
+* `linuxkit/kernel-perf:6.6.13`
+* `linuxkit/kernel-perf:6.6.13-c0d96951e9892a7447a8e7965d2d6bd7e621c3fd`
+* `linuxkit/kernel-perf:6.6.13-amd64`
+* `linuxkit/kernel-perf:6.6.13-c0d96951e9892a7447a8e7965d2d6bd7e621c3fd-amd64`
+
+## Additional Contributions
 
 In addition to the official images, there are also some
 [scripts](../contrib/foreign-kernels) which repackage kernels packages
@@ -32,7 +66,6 @@ use cases for the promising IoT scenarios. All -rt patches are grabbed from
 https://www.kernel.org/pub/linux/kernel/projects/rt/. But so far we just
 enable it over 4.14.x.
 
-
 ## Loading kernel modules
 
 Most kernel modules are autoloaded with `mdev` but if you need to `modprobe` a module manually you can use the `modprobe` package in the `onboot` section like this:
@@ -45,22 +78,36 @@ Most kernel modules are autoloaded with `mdev` but if you need to `modprobe` a m
 ## Compiling external kernel modules
 
 This section describes how to build external (out-of-tree) kernel
-modules. It is assumed you have the source available to those modules,
-and require the correct kernel version headers and compile tools.
+modules. You need the following to build external modules. All of
+these are to be built for a specific version of the kernel. For
+the examples, we will assume 5.10.104; replace with your desired
+version.
 
-The LinuxKit kernel packages include `kernel-dev.tar` which contains
+* source available to your modules - you need to get those on your own
+* kernel development headers - available in the `linuxkit/kernel` image as `kernel-dev.tar`, e.g. `linuxkit/kernel:5.10.104`
+* OS with sources and compiler - this **must** be the exact same version as that used to compile the kernel
+
+As described above, the `linuxkit/kernel` images include `kernel-dev.tar` which contains
 the headers and other files required to compile kernel modules against
 the specific version of the kernel. Currently, the headers are not
 included in the initial RAM disk, but it is possible to compile custom
 modules offline and then include the modules in the initial RAM disk.
 
-There is a [example](../test/cases/020_kernel/010_kmod_4.9.x), but
+The source is available as the same name as the `linuxkit/kernel` image, with the addition of `-builder` on the tag.
+For example:
+
+* `linuxkit/kernel:5.10.92` has builder `linuxkit/kernel:5.10.92-builder`
+* `linuxkit/kernel:5.15.15` has builder `linuxkit/kernel:5.15.15-builder`
+
+With the above in hand, you can create a multi-stage `Dockerfile` build to compile your modules.
+There is an [example](../test/cases/020_kernel/113_kmod_5.10.x), but
 basically one can use a multi-stage build to compile the kernel
 modules:
 
-```
-FROM linuxkit/kernel:4.9.33 AS ksrc
-FROM linuxkit/alpine:<hash> AS build
+```dockerfile
+FROM linuxkit/kernel:5.10.104 AS ksrc
+FROM linuxkit/kernel:5.10.104-builder AS build
+
 RUN apk add build-base
 
 COPY --from=ksrc /kernel-dev.tar /
@@ -73,55 +120,275 @@ To use the kernel module, we recommend adding a final stage to the
 Dockerfile above, which copies the kernel module from the `build`
 stage and performs a `insmod` as the entry point. You can add this
 package to the `onboot` section in your YAML
-file. [kmod.yml](../test/cases/020_kernel/010_kmod_4.9.x/kmod.yml)
+file. [test.yml](../test/cases/020_kernel/113_kmod_5.10.x/test.yml)
 contains an example for the configuration.
 
+### Builder Backups
 
-## Modifying the kernel config
+As described above, the OS builder is referenced via `<kernel-image>-builder`, e.g.
+`linuxkit/kernel:5.15.15-builder`.
 
-Each series of kernels has a config file dedicated to it
-in [../kernel/](../kernel),
-e.g.
-[config-4.9.x-x86_64](../kernel/config-4.9.x-x86_64),
-which is applied during the kernel build process.
+As a fallback, in case the `-builder` image is not available or you cannot access it from your development environment,
+you have 3 total places to determine the correct version of the OS image with sources and compiler:
 
-If you need to modify the kernel config, `make kconfig` in
-the [kernel](../kernel) directory will create a local
-`linuxkit/kconfig` Docker image, which contains the patched sources
-for all support kernels and architectures in
-`/linux-4.<minor>.<rev>`. The kernel source also has the kernel config
-copied to the default kernel config.
+* `-builder` tag added to the kernel version, e.g. `linuxkit/kernel:5.10.104-builder`
+* labels on the kernel image, e.g. `docker inspect linuxkit/kernel:5.10.104 | jq -r '.[].Config.Labels["org.mobyproject.linuxkit.kernel.buildimage"]'`
+* `/kernel-builder` file in the kernel image
 
-Running the image like:
+You **should** use `-builder` tag as the `AS build` in your `Dockerfile`, but you **can** use
+the direct source, extracted from the labels or `/kernel-builder` file in the kernel image, in the `AS build`.
 
-```sh
-docker run --rm -ti -v $(pwd):/src linuxkit/kconfig
+For example, in the case of `5.10.104`, the label and `/kernel-builder` file show `linuxkit/alpine:2be490394653b7967c250e86fd42cef88de428ba`,
+so you can use either `linuxkit/alpine:2be490394653b7967c250e86fd42cef88de428ba` or
+`linuxkit/kernel:5.10.104-builder` to build the modules.
+
+Thus, the following are equivalent:
+
+```dockerfile
+FROM linuxkit/kernel:5.10.104 AS ksrc
+FROM linuxkit/kernel:5.10.104-builder AS build
 ```
 
-will give you a interactive shell where you can modify the kernel
-configuration you want, either by editing the config file, or via
-`make menuconfig` etc. Once you are done, save the file as `.config`
-and copy it back to the source tree,
-e.g. `/src/kernel-config-4.9.x-x86_64`.
-
-You can also configure other architectures other than the native
-one. For example to configure the arm64 kernel on x86_64, use:
-
+```dockerfile
+FROM linuxkit/kernel:5.10.104 AS ksrc
+FROM linuxkit/alpine:2be490394653b7967c250e86fd42cef88de428ba AS build
 ```
-make ARCH=arm64 defconfig
-make ARCH=arm64 oldconfig # or menuconfig
+
+## Building and Modifying
+
+This section describes how to build kernels, and how to modify existing ones.
+
+Throughout the document, the terms used are:
+
+* kernel version: actual semver version of a kernel, e.g. `6.6.13` or `5.15.27`
+* kernel series: major.minor version of a kernel, e.g. `6.6.x` or `5.15.x`
+
+Throughout this document, the architecture used is the kernel-recognized one, available
+on most systems as `uname -m`, e.g. `aarch64` or `x86_64`. You may be familiar with the alpine
+or golang one, e.g. `amd64` or `amd64`, which are not used here.
+
+**Note:** After changing _and committing any changes_ to the kernel directory or any
+subdirectories, you must update tests, examples and other dependencies. This is done
+via:
+
+```bash
+make update-kernel-yamls
 ```
 
+Each series of kernels has a dedicated directory in [../kernel/](../kernel),
+e.g. [6.6.x](../kernel/6.6.x) or [5.15.x](../kernel/5.15.x).
+Variants, like rt kernels, have their own directory as well, e.g. [5.11.x-rt](../kernel/5.11.x-rt).
+However, for variants, the patches from _both_ the common kernel, e.g. [5.11.x](../kernel/5.11.x),
+and the variant, e.g. [5.11.x-rt](../kernel/5.11.x-rt), are applied, and the configs from _both_ are combined.
+
+Within the series-dedicated directory, there are:
+
+* kernel config file for each architecture named `config-<arch>`, e.g. [6.6.13/config-x86_64](../kernel/6.6.13/config-x86_64), one per target architecture. 
+* optional patches directory, e.g. [6.6.13/patches](../kernel/6.6.13/patches), which contains patches to apply to the kernel source
+
+The config file and patches are applied during the kernel build process.
+
 **Note**: We try to keep the differences between kernel versions and
 architectures to a minimum, so if you make changes to one
 configuration also try to apply it to the others. The script [kconfig-split.py](../scripts/kconfig-split.py) can be used to compare kernel config files. For example:
 
 ```sh
-../scripts/kconfig-split.py config-4.9.x-aarch64 config-4.9.x-x86_64
+../scripts/kconfig-split.py 5.15.x/config-aarch64 5.15.x/config-x86_64
 ```
 
 creates a file with the common and the x86_64 and arm64 specific
-config options for the 4.9.x kernel series.
+config options for the 5.15.x kernel series.
+
+**Note**: The CI pipeline does *not* push out kernel images.
+Anyone modifying a kernel should:
+
+1. Follow the steps below for the desired changes and commit them.
+1. Run appropriate `make build` or variants to ensure that it works.
+1. Open a PR with the changes. This may fail, as the CI pipeline may not have access to the modified kernels.
+1. A maintainer should run `make push` to push out the images.
+1. Run (or rerun) the tests.
+
+#### Build options
+
+The targets and variants for building are as follows:
+
+* `make build` - make all kernels in the version list and their variants
+* `make build-<version>` - make all variants of a specific kernel version
+* `make buildkernel-<version>` - make all variants of a specific kernel version
+* `make buildplainkernel-<version>` - make just the provided version's kernel
+* `make builddebugkernel-<version>` - make just the provided version's debug kernel
+* `make buildtools-<version>` - make just the provided version's tools
+
+To push:
+
+* `make push` - push all kernels in the version list and their variants
+* `make push-<version>` - push all variants of a specific kernel version
+
+Finally, for convenience:
+
+* `make list` - list all kernels in the version list
+
+By default, it builds for all supported architectures. To build just for a specific
+architecture:
+
+```sh
+make build ARCH=amd64
+```
+
+The variable `ARCH` should use the golang variants only, i.e. `amd64` and `arm64`.
+
+To build for multiple architectures, call it multiple times:
+
+```sh
+make build ARCH=amd64
+make build ARCH=arm64
+```
+
+When building for a specific architecture, the build process will use your local
+Docker, passing it `--platforms` for the architecture. If you have a builder on a different
+architecture, e.g. you are running on an Apple Silicon Mac (arm64) and want to build for
+`x86_64` without emulating (which can be very slow), you can use the `BUILDER` variable:
+
+```sh
+make build ARCH=x86_64 BUILDER=remote-amd64-builder
+```
+
+Builder also supports a builder pattern. If `BUILDER` contains the string `{{.Arch}}`,
+it will be replaced with the architecture being built.
+
+For example:
+
+```sh
+make build ARCH=x86_64 BUILDER=remote-{{.Arch}}-builder
+make build ARCH=aarch64 BUILDER=remote-{{.Arch}}-builder
+```
+
+will build `x86_64` on `remote-amd64-builder` and `aarch64` on `remote-arm64-builder`.
+
+Finally, if no `BUILDER` is specified, the build will look for a builder named
+`linuxkit-linux-{{.Arch}}-builder`, e.g. `linuxkit-linux-amd64-builder` or
+`linuxkit-linux-arm64-builder`. If that builder does not exist, it will fall back to
+your local Docker setup.
+
+### Modifying the kernel config
+
+The process of modifying the kernel configuration is as follows:
+
+1. Create a `linuxkit/kconfig` container image: `make kconfig`. This is not pushed out.
+1. Run a container based on `linuxkit/kconfig`.
+1. In the container, modify the config to suit your needs using normal kernel tools like `make defconfig` or `make menuconfig`.
+1. Save the config from the image.
+
+The `linuxkit/kconfig` image contains the patched sources
+for all support kernels and architectures in `/linux-<major>.<minor>.<rev>`.
+The kernel source also has the kernel config copied to the default kernel config location,
+so that `make menuconfig` and `make defconfig` work correctly.
+
+Run the container as follows:
+
+```sh
+docker run --rm -ti -v $(pwd):/src linuxkit/kconfig
+```
+
+This will give you a interactive shell where you can modify the kernel
+configuration you want, while mounting the directory, so that you can save the
+modified config.
+
+To create or modify the config, you must cd to the correct directory,
+e.g.
+
+```sh
+cd /linux-6.6.13
+# or
+cd /linux-5.15.27
+```
+
+Now you can build the config.
+
+When `make defconfig` or `make menuconfig` is done,
+the modified config file will be in `.config`; save the file back to `/src`,
+e.g.
+
+```sh
+cp .config /src/6.6.x/config-x86_64
+```
+
+You can also configure other architectures other than the native
+one. For example to configure the arm64 kernel on x86_64, use:
+
+```sh
+make ARCH=arm64 defconfig
+make ARCH=arm64 oldconfig # or menuconfig
+```
+
+Note that the generated file **must** be final. When you actually build the kernel,
+it will check that running `make defconfig` will have no changes. If there are changes,
+the build will fail.
+
+The easiest way to check it is to rerun `make defconfig` inside the kconfig container.
+
+1. Finish your creation of the config file, as above.
+1. Copy the `.config` file to the target location, as above.
+1. Copy the `.config` file to the source location for defconfig, e.g. `cp .config arch/x86/configs/x86_64_config` or `cp. config /linux/arch/arm64/configs/defconfig`
+1. Run `make defconfig` again, and check that there are no changes, e.g. `diff .config arch/x86/configs/x86_64_config` or `diff .config /linux/arch/arm64/configs/defconfig`
+
+If there are no differences, then you can commit the new config file.
+
+Finally, test that you can build the kernel with that config as `make build-<version>`, e.g. `make build-5.15.148`.
+
+## Adding a new kernel version
+
+If you want to add a new kernel version within an existing series, e.g. `5.15.27` already exists
+and you want to add (or replace it with) `5.15.148`, apply the following process.
+
+1. Determine the series, i.e. the kernel major.minor version, followed by `x`. E.g. for `5.15.148`, the series is `5.15.x`.
+1. Modify the `KERNEL_VERSION` in the `build-args` file in the series directory to the new version. E.g. `5.15.x/build-args`.
+1. Create a new `linuxkit/kconfig` container image: `make kconfig`. This is not pushed out.
+1. Run a container based on `linuxkit/kconfig`.
+```sh
+docker run --rm -ti -v $(pwd):/src linuxkit/kconfig
+```
+1. In the container, change directory to the kernel source directory for the new version, e.g. `cd /linux-5.15.148`.
+1. Run `make defconfig` to create the default config file.
+1. If the config file has changed, copy it out of the container and check it in, e.g. `cp .config /src/5.15.x/config-x86_64`.
+1. Repeat for other architectures.
+1. Commit the changed config files.
+1. Test that you can build the kernel with that config as `make build-<version>`, e.g. `make build-5.15.148`.
+
+## Adding a new kernel series
+
+To add a new kernel series, you need to:
+
+1. Create new directory for the series, e.g. `6.7.x`
+1. Create config files for each architecture in that directory
+1. Optionally, create a `patches/` subdirectory in that directory with any patches to add
+1. Create a `build-args` file in that directory with at least the following settings:
+```bash
+KERNEL_VERSION=<version>
+KERNEL_SERIES=<series>
+BUILD_IMAGE=linuxkit/alpine:<builder>
+```
+
+Since the last major series likely is the best basis for the new one, subject to additional modifications, you can use
+the previous one as a starting point.
+
+1. Make the directory for the new series, e.g. `mkdir 7.0.x`
+1. Create a new `linuxkit/kconfig` container image: `make kconfig`. This is not pushed out.
+1. Run a container based on `linuxkit/kconfig`.
+```sh
+docker run --rm -ti -v $(pwd):/src linuxkit/kconfig
+```
+1. In the container, change directory to the kernel source directory for the new version, e.g. `cd /linux-7.0.5`.
+1. Copy the existing config file for the previous series, e.g. `cp /src/6.6.x/config-x86_64 .config`.
+1. Run `make oldconfig` to create the config file for the new series from the old one. Answer any questions.
+1. Save the newly generated config file `.config` to the source directory, e.g. `cp .config /src/7.0.x/config-x86_64`.
+1. Repeat for other architectures.
+1. Commit the new config files.
+1. Test that you can build the kernel with that config as `make build-<version>`, e.g. `make build-7.0.5`.
+
+In addition, there are tests that are applied to a specific kernel version, notably the tests in
+[020_kernel](../test/cases/020_kernel/). You will need to add a new test case for the new series,
+copying an existing one and modifying it as needed.
 
 ## Building and using custom kernels
 
@@ -149,7 +416,7 @@ appended. Then you can also override the Hub organisation to use the
 image elsewhere with (and also disable image signing):
 
 ```sh
-make ORG=<your hub org> NOTRUST=1
+make ORG=<your hub org>
 ```
 
 The image will be uploaded to Hub and can be use in a YAML file as
@@ -322,7 +589,7 @@ yourself:
 
 ```sh
 cd kernel
-make ORG=<foo> NOTRUST=1 push_zfs_4.9.x # or different kernel version
+make ORG=<foo> push_zfs_4.9.x # or different kernel version
 ```
 
 will build and push a `zfs-kmod-4.9.<version>` image to Docker Hub
@@ -347,3 +614,31 @@ Alpine `zfs` utilities are available in `linuxkit/alpine` and the
 version of the kernel module should match the version of the
 tools. The container where you run the `zfs` tools might also need
 `CAP_SYS_MODULE` to be able to load the kernel modules.
+
+## Kernels in examples and tests
+
+All of the linuxkit `.yml` files use the images from `linuxkit/kernel:<tag>`.
+
+When updating the kernel, you run commands to update the tests. The updates to any file that contains
+references to `linuxkit/kernel` in this repository work as follows:
+
+- Semver tags are replaced by the most recent kernel version. For example, `linuxkit/kernel:5.10.104` will become `6.6.13` when available, and then `6.6.15`, and then `7.0.1`, etc. The highest semver always is used.
+- Semver+hash tags are replaced by the most recent hash and patch version for that series. For example, `linuxkit/kernel:5.10.104-abcdef1234` will become `5.10.104-aaaa54232` (same semver, newer hash), and then `5.10.105-bbbb12345` (newer semver, newer hash), etc. The highest semver+hash always is used.
+
+This is not an inherent characteristic of `linuxkit` tool, which **never** will change your `.yml` files. It is part of
+the update process for yml files _in this repository_.
+
+The net of the above is the following rule:
+
+* If you want a reference to a specific kernel series, e.g. a test or example that works only with `5.10.x`, then use a specific hash, e.g. `linuxkit/kernel:5.10.104-abcdef1234`. The hash and patch version will update, but not more. The most common use case for this is kernel version-specific tests.
+* If you want a reference to the most recent kernel, whatever version it is, then use a semver tag, e.g. `linuxkit/kernel:6.6.13`. The most common use case for this is examples that work with any kernel version, which is the vast majority of cases.
+
+You can get the current hash by executing the following:
+
+```bash
+$ cd kernel
+$ make tag-plain-kernel-<version>
+# for example:
+$ make tag-plain-kernel-6.6.13
+linuxkit/kernel:6.6.13-3a8b3faf92390265b1fbee792b9a3fe14d14c26e
+```

docs/logging.md

@@ -0,0 +1,94 @@
+# Logging
+
+By default LinuxKit will write onboot and service logs directly to files in
+`/var/log` and `/var/log/onboot`.
+
+It is tricky to write the logs to a disk or a network service as no disks
+or networks are available until the `onboot` containers run. We work around
+this by splitting the logging into 2 pieces:
+
+1. `memlogd`: an in-memory circular buffer which receives logs (including
+   all the early `onboot` logs)
+2. a log writing `service` that starts later and can download and process
+   the logs from `memlogd`
+
+To use this new logging system, you should add the `memlogd` container to
+the `init` block in the LinuxKit yml. On boot `memlogd` will be started
+from `init.d` and it will listen on a Unix domain socket:
+
+```
+/var/run/linuxkit-external-logging.sock
+```
+
+The `init`/`service` process will look for this socket and redirect the
+`stdout` and `stderr` of both `onboot` and `services` to `memlogd`.
+
+## memlogd: an in-memory circular buffer
+
+The `memlogd` daemon reads the logs from the `onboot` and `services` containers
+and stores them together with a timestamp and the name of the originating
+container in a circular buffer in memory.
+
+The contents of the circular buffer can be read over the Unix domain socket
+```
+/var/run/memlogq.sock
+```
+
+The circular buffer has a fixed size (overridden by the command-line argument
+`-max-lines`) and when it fills up, the oldest messages will be overwritten.
+
+To store the logs somewhere more permanent, for example a disk or a remote
+network service, a service should be added to the yaml which connects to
+`memlogd` and streams the logs. The `logwrite` service described below shows
+how to do this.
+
+### Message format
+
+The format used to read logs is similar to [kmsg](https://www.kernel.org/doc/Documentation/ABI/testing/dev-kmsg):
+```
+<timestamp>,<log>;<body>
+```
+where `<timestamp>` is an RFC3339-formatted timestamp, `<log>` is the name of
+the log (e.g. `docker-ce.out`) and `<body>` is the output. The `<log>` must
+not contain the character `;`.
+
+## logwrite: writing logs to disk
+
+The service `pkg/logwrite` connects to `memlogd` and streams the logs to files
+in `/var/log`. The logs are automatically rotated; by default each file has
+a maximum size of 1 MiB and up to 10 files are kept per log. The arguments
+`-max-log-files` and `-max-log-size` can be used to override these defaults.
+
+Here is an example log file:
+```
+# cat /var/log/onboot.001-dhcpcd.out 
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: waiting for carrier
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: carrier acquired
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out DUID 00:01:00:01:22:d4:93:05:02:50:00
+:00:00:06
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: IAID 00:00:00:06
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: adding address fe80::f346:56a6:590d:5ea4
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: soliciting an IPv6 router
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: soliciting a DHCP lease
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: offered 192.168.65.8 from 192.168.65.1 `vpnkit'
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: leased 192.168.65.8 for 7200 se
+conds
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: adding route to 192.168.65.0/24
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out eth0: adding default route via 192.16
+8.65.1
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out exiting due to oneshot
+2018-07-08T09:16:53Z onboot.001-dhcpcd.out dhcpcd exited
+```
+
+## Current issues and limitations:
+
+- No docker logger plugin support yet - it could be nice to add support to
+  memlogd, so the docker container logs would also be gathered in one place
+- No syslog compatibility at the moment and `/dev/log` doesn’t exist. This
+  socket could be created to keep syslog compatibility, e.g. by using
+  https://github.com/mcuadros/go-syslog. Processes that require syslog should
+  then be able to log directly to memlogd.
+- Currently no direct external hooks exposed - but options available that
+  could be added. Should also be possible to pipe output to e.g. `oklog`
+  from `logread` (https://github.com/oklog/oklog)
+

docs/losetup.md

@@ -0,0 +1,27 @@
+# LinuxKit losetup
+
+Image to setup a loop device backed by a regular file in a [linuxkit](https://github.com/linuxkit/linuxkit)-generated image. The typical use case is to have a portable storage location which can be used to persist settings or other files. Can be combined with the `linuxkit/dm-crypt` package for protection.
+
+## Usage
+
+The setup is a one time step during boot:
+
+```yaml
+onboot:
+  - name: losetup
+    image: linuxkit/losetup:<hash>
+    command: ["/usr/bin/loopy", "-c", "/var/test.img"]
+```
+
+The above will associate the file `/var/test.img` with `/dev/loop0` and will also create it if it's not present.
+
+The container by default bind-mounts `/var:/var` and `/dev:/dev`. Usually the loop-file will reside on external storage which should be typically mounted under `/var` hence the choice of the defaults. If the loop-file is located somewhere else and you need a different bind-mount for it then do not forget to explicitly bind-mount `/dev:/dev` as well or else `losetup` will fail.
+
+### Options
+
+|Option|Default|Required|Notes|
+|---|---|---|---|
+|`-c` or `--create`||No|Creates the file if not present. If `--create` is not specified and the file is missing then the loop setup will obviously fail.|
+|`-s` or `--size`|10|No|If `--create` was specified and the file is not present then this sets the size in MiB of the created file. The file will be filled from `/dev/zero`.|
+|`-d` or `--dev`|`/dev/loop0`|No|Loop device which should be associated with the file.|
+|`<file>`||**Yes**|The file to use as backing storage.|

docs/metadata.md

@@ -63,6 +63,21 @@ This hierarchy can then be used by individual containers, who can bind
 mount the config sub-directory into their namespace where it is
 needed.
 
+## A note on SSH
+
+Supported providers will extract public keys from metadata to a file
+located at `/run/config/ssh/authorized_keys`.  You must bind this path
+into the `sshd` namespace in order to make use of these keys.  Use a
+configuration similar to the one shown below to enable root login
+based on keys from the metadata service:
+
+```
+  - name: sshd
+    image: linuxkit/sshd:4696ba61c3ec091328e1c14857d77e675802342f
+    binds.add:
+     - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
+```
+
 # Metadata image creation
 
 `linuxkit run` backends accept two options to pass metadata to the VM in a platform specific
@@ -101,9 +116,23 @@ hostname and populate the `/run/config/ssh/authorized_keys` from metadata.
 AWS userdata is extracted from `http://169.254.169.254/latest/user-data` and
 and made available in `/run/config/userdata`.
 
+## Hetzner
+
+Hetzner metadata is reached via the following URL
+(`http://169.254.169.254/latest/meta-data/`) and currently we extract the
+hostname and populate the `/run/config/ssh/authorized_keys` from metadata.
+
+Hetzner userdata is extracted from `http://169.254.169.254/latest/user-data` and
+and made available in `/run/config/userdata`.
 
 ## HyperKit
 
 HyperKit does not distinguish metadata and userdata, it's simply
 refered to as data, which is passed to the VM as a disk image
 in ISO9660 format.
+
+## Virtualization.Framework
+
+Virtualization.Framework does not distinguish metadata and userdata, it's simply
+refered to as data, which is passed to the VM as a disk image
+in ISO9660 format.

docs/packages.md

@@ -7,23 +7,37 @@ packages, as it's very easy. Packages are the unit of customisation
 in a LinuxKit-based project, if you know how to build a container,
 you should be able to build a LinuxKit package.
 
-All LinuxKit packages are:
-- Signed with Docker Content Trust.
-- Enabled with multi-arch manifests to work on multiple architectures.
-- Derived from well-known (and signed) sources for repeatable builds.
+All official LinuxKit packages are:
+- Enabled with multi-arch indexes to work on multiple architectures.
+- Derived from well-known sources for repeatable builds.
 - Built with multi-stage builds to minimise their size.
 
 
 ## CI and Package Builds
+
 When building and merging packages, it is important to note that our CI process builds packages. The targets `make ci` and `make ci-pr` execute `make -C pkg build`. These in turn execute `linuxkit pkg build` for each package under `pkg/`. This in turn will try to pull the image whose tag matches the tree hash or, failing that, to build it.
 
-We do not want the builds to happen with each CI run for two reasons:
+Any released image, i.e. any package under `pkg/` that has _not_ changed as
+part of a pull request,
+already will be released to Docker Hub. This will cause it to download that image, rather
+than try to build it.
+
+Any non-releaed image, i.e. any package under `pkg/` that _has_ changed as part of
+a pull request, will not be in Docker Hub until the PR has merged.
+This will cause the download to fail, leading `linuxkit pkg build` to try and build the
+image and save it in the cache.
+
+This does have two downsides:
 
 1. It is slower to do a package build than to just pull the latest image.
 2. If any of the steps of the build fails, e.g. a `curl` download that depends on an intermittent target, it can cause all of CI to fail.
 
-Thus, if, as a maintainer, you merge any commits into a `pkg/`, even if the change is documentation alone, please do a `linuxkit package push`.
+In the past, each PR required a maintainer to build, and push to Docker Hub, every
+changed package in `pkg/`. This placed the maintainer in the PR cycle, with the
+following downsides:
 
+1. A maintainer had to be involved in every PR, not just reviewing but actually building and pushing. This reduces the ability for others to contribute.
+1. The actual package is pushed out by a person, violating good supply-chain practice.
 
 ## Package source
 
@@ -36,11 +50,13 @@ A package source consists of a directory containing at least two files:
 
 - `image` _(string)_: *(mandatory)* The name of the image to build
 - `org` _(string)_: The hub/registry organisation to which this package belongs
+- `dockerfile` _(string)_: The dockerfile to use to build this package, must be in this directory or below (default: `Dockerfile`)
 - `arches` _(list of string)_: The architectures which this package should be built for (valid entries are `GOARCH` names)
+- `extra-sources` _(list of strings)_: Additional sources for the package outside the package directory. The format is `src:dst`, where `src` can be relative to the package directory and `dst` is the destination in the build context. This is useful for sharing files, such as vendored go code, between packages.
 - `gitrepo` _(string)_: The git repository where the package source is kept.
 - `network` _(bool)_: Allow network access during the package build (default: no)
-- `disable-content-trust` _(bool)_: Disable Docker content trust for this package (default: no)
 - `disable-cache` _(bool)_: Disable build cache for this package (default: no)
+- `buildArgs` will forward a list of build arguments down to docker. As if `--build-arg` was specified during `docker build`
 - `config`: _(struct `github.com/moby/tool/src/moby.ImageConfig`)_: Image configuration, marshalled to JSON and added as `org.mobyproject.config` label on image (default: no label)
 - `depends`: Contains information on prerequisites which must be satisfied in order to build the package. Has subfields:
     - `docker-images`: Docker images to be made available (as `tar` files via `docker image save`) within the package build context. Contains the following nested fields:
@@ -52,9 +68,9 @@ A package source consists of a directory containing at least two files:
 ### Prerequisites
 
 Before you can build packages you need:
-- Docker version 17.06 or newer. If you are on a Mac you also need
-  `docker-credential-osxkeychain.bin`, which comes with Docker for Mac.
-- `make`, `notary`, `base64`, `jq`, and `expect`
+- Docker version 19.03 or newer.
+- If you are on a Mac you also need `docker-credential-osxkeychain.bin`, which comes with Docker for Mac.
+- `make`, `base64`, `jq`, and `expect`
 - A *recent* version of `manifest-tool` which you can build with `make
   bin/manifest-tool`, or `go get github.com:estesp/manifest-tool`, or
   via the LinuxKit homebrew tap with `brew install --HEAD
@@ -65,68 +81,258 @@ Further, when building packages you need to be logged into hub with
 `docker login` as some of the tooling extracts your hub credentials
 during the build.
 
+### Build Targets
+
+LinuxKit builds packages as docker images. It deposits the built package as a docker image in one or both of two targets:
+
+* the linuxkit cache, which is at `~/.linuxkit/cache/` (configurable)
+* the docker image cache (optional)
+
+The package _always_ is built and saved in the linuxkit cache. However, you _also_ can load the package for the current
+architecture, if available, into the docker image cache.
+
+If you want to build images and test and run them _in a standalone_ fashion locally, then you should add the docker image cache.
+Otherwise, you don't need anything more than the default linuxkit cache. LinuxKit defaults to building OS images using docker
+images from this cache, only looking in the docker cache if instructed to via `linuxkit build --docker`.
+
+In the linuxkit cache, it creates all of the layers, the manifest that can be uploaded
+to a registry, and the multi-architecture index. If an image already exists for a different architecture in the cache,
+it updates the index to include additional manifests created.
+
+The order of building is as follows:
+
+1. Build the image to the linuxkit cache
+1. If `--docker` is provided, load the image into the docker image cache
+
+For example:
+
+```bash
+linuxkit pkg build pkg/foo           # builds pkg/foo and places it in the linuxkit cache
+linuxkit pkg build pkg/foo --docker  # builds pkg/foo and places it in the linuxkit cache and also loads it into docker
+```
+
+#### Build Platforms
+
+By default, `linuxkit pkg build` builds for all supported platforms in the package's `build.yml`, whose syntax is available
+[here][Package source]. If no platforms are provided in the `build.yml`, it builds for all platforms that linuxkit supports.
+As of this writing, those are:
+
+* `linux/amd64`
+* `linux/arm64`
+* `linux/s390x`
+
+You can choose to skip one of the platforms from `build.yml` or those selected
+by default using the `--skip-platforms` flag.
+
+For example:
+
+```
+linuxkit pkg build --skip-platforms linux/s390x ...
+```
+
+You can override the target build platform by passing it the `--platforms` option:
+
+```
+linuxkit pkg build --platforms <platform1,platform2,...platformN>
+```
+
+The options for `--platforms` are identical to those for [docker build](https://docs.docker.com/engine/reference/commandline/build/).
+An example is available in the official [buildx documentation](https://docs.docker.com/buildx/working-with-buildx/#build-multi-platform-images).
+
+Given that this is linuxkit, i.e. all builds are for linux, the `OS` part would seem redundant, and it should be sufficient to pass `--platform arm64`. However, for complete consistency, the _entire_ platform, e.g. `--platforms linux/amd64,linux/arm64`, must be provided.
+
+#### Where it builds
+
+You are running the `linuxkit pkg build` command on a single platform, e.g. your local linux cloud instance running on `amd64`, or
+a MacBook with Apple Silicon running on `arm64`.
+
+How does linuxkit determine where to build the target images?
+
+linuxkit uses [buildkit](https://github.com/moby/buildkit) directly to build all images.
+It uses docker contexts to determine _where_ to run those buildkit containers, based on the target
+architecture.
+
+When running a package build, linuxkit looks for a container named `linuxkit-builder`, running the appropriate
+version of buildkit. If it cannot find a container with that name, it creates it.
+If the container already exists but is not running buildkit, or if the version is incorrect, linuxkit stops and removes
+the existing `linuxkit-builder` container and creates one running the correct version of buildkit.
+
+When linuxkit needs to build a package for a particular architecture:
+
+1. If a context for that architecture was provided, use that context, looking for and/or starting a buildkit container named `linuxkit-builder`.
+1. If no context for that architecture was provided, use the `default` context.
+
+The actual building then will be one of:
+
+1. native, if the provided context has the same architecture as the target build architecture; else
+1. cross-build, if the provided context has a different architecture, but the package's `Dockerfile` supports cross-building; else
+1. emulated build, using docker's qemu binfmt capabilities
+
+Cross-building, i.e. building on one platform using that platform's binaries to create outputs for a different platform,
+depends on the package's `Dockerfile`. Details are available in the
+[official Docker buildx docs](https://docs.docker.com/buildx/working-with-buildx/#build-multi-platform-images).
+
+* if the image is just `FROM something`, then it runs it under qemu using binfmt
+* if the image is `FROM --platform=$BUILDPLATFORM something`, then it runs it using the local architecture, invoking cross-builders
+
+Read the official docs to learn more how to leverage cross-building with buildx.
+
+**Important:** When building, if the local architecture is not one of those being build,
+selecting `--docker` to load the images into the docker image cache will result in an error.
+You _must_ be building for the local architecture - optionally for others as well - in order to
+pass the `--docker` option.
+
+#### Providing native builder nodes
+
+linuxkit is capable of using native build nodes to do the build, even remotely. To do so, you must:
+
+1. Create a [docker context](https://docs.docker.com/engine/context/working-with-contexts/) that references the build node
+1. Tell linuxkit to use that context for that architecture
+
+linuxkit will then use that provided context to look for and/or start a container in which to run buildkit for that architecture.
+
+linuxkit looks for contexts in the following descending order of priority:
+
+1. CLI option `--builders <platform>=<context>,<platform>=<context>`, e.g. `--builders linux/arm64=linuxkit-arm64,linux/amd64=default`
+1. Environment variable `LINUXKIT_BUILDERS=<platform>=<context>,<platform>=<context>`, e.g. `LINUXKIT_BUILDERS=linux/arm64=linuxkit-arm64,linux/amd64=default`
+1. Existing context named `linuxkit-<platform>`, e.g. `linuxkit-linux-arm64` or `linuxkit-linux-s390x`, with "/" replaced by "-", as "/" is an invalid character.
+1. Default context
+
+If a builder name is provided for a specific platform, and it doesn't exist, it will be treated as a fatal error.
+
+#### Examples
+
+##### Simple build
+
+There are no contexts starting with `linuxkit-`, no environment variable `LINUXKIT_BUILDERS`, no command-line argument `--builders`.
+
+linuxkit will build any requested packages using `default` context on the local platform, with a container (created, if necessary) named `linuxkit-builder`.
+Builds for the same architecture will be native, builds for other platforms will use either qemu or cross-building.
+
+##### Specified target
+
+You create a context named `my-remote-arm64` and then run:
+
+```bash
+linuxkit pkg build --platforms=linux/arm64,linux/amd64 --builders linux/arm64=my-remote-arm64
+```
+
+linuxkit will build:
+
+* for arm64 using the context `my-remote-arm64`, since you specified in `--builders` to use `my-remote-arm64` for `linux/arm64`
+* for amd64 using the context `default`, as that is the default fallback
+
+The same would happen if you used `LINUXKIT_BUILDERS=linux/arm64=my-remote-arm64` instead of the `--builders` flag.
+
+In both cases - the remote context `my-remote-arm64` and the local `default` context - it will do the build inside
+a container named `linuxkit-builder`.
+
+##### Named context
+
+You create a context named `linuxkit-linux-arm64` and then run:
+
+```bash
+linuxkit pkg build --platforms=linux/arm64,linux/amd64
+```
+
+linuxkit will build:
+
+* for arm64 using the context `linuxkit-linux-arm64`, since there is a context with the name `linuxkit-<platform>`, and you did not override it using `--builders` or the environment variable `LINUXKIT_BUILDERS`
+* for amd64 using the context `default` and the `linuxkit` builder, as that is the default fallback
+
+##### Combination
+
+You create a context named `linuxkit-linux-arm64`, and another named `my-remote-builder-amd64` and then run:
+
+```bash
+linuxkit pkg build --platforms=linux/arm64,linux/amd64 --builders linux/amd64=my-remote-builder-amd64
+```
+
+linuxkit will build:
+
+* for arm64 using the context `linuxkit-linux-arm64`, since there is a context with the name `linuxkit-<platform>`, and you did not override that particular architecture using `--builders` or the environment variable `LINUXKIT_BUILDERS`
+* for amd64 using the context `my-remote-builder-amd64`, since you specified for that architecture using `--builders`
+
+The same would happen if you used `LINUXKIT_BUILDERS=linux/arm64=my-remote-builder-amd64` instead of the `--builders` flag.
+
+##### Missing context
+
+You do not have a context named `my-remote-arm64`, and run:
+
+```bash
+linuxkit pkg build --platforms=linux/arm64 --builders linux/arm64=my-remote-arm64
+```
+
+linuxkit will try to build for `linux/arm64` using the context `my-remote-arm64`. Since that context does not exist, you will get an error.
+
+##### Preset build arguments
+
+When building packages, the following build-args automatically are set for you:
+
+* `SOURCE` - the source repository of the package
+* `REVISION` - the git commit that was used for the build
+* `GOPKGVERSION` - the go package version or pseudo-version per https://go.dev/ref/mod#glos-pseudo-version
+* `PKG_HASH` - the git tree hash of the package directory, e.g. `45a1ad5919f0b6acf0f0cf730e9434abfae11fe6`; tag part of `linuxkit pkg show-tag`
+* `PKG_IMAGE` - the name of the image that is being built, e.g. `linuxkit/init`; image name part of `linuxkit pkg show-tag`. Combine with `PKG_HASH` for the full tag.
+
+Note that the above are set **only** if you do not set them in `build.yaml`. Your settings _always_
+override these built-in ones.
+
+To use them, simply address them in your `Dockerfile`:
+
+```dockerfile
+ARG SOURCE
+```
+
 ### Build packages as a maintainer
 
-If you have write access to the `linuxkit` organisation on hub, you
-should also be set up with signing keys for packages and your signing
-key should have a passphrase, which we call `<passphrase>` throughout.
-
 All official LinuxKit packages are multi-arch manifests and most of
-them are available for `amd64`, `arm64`, and `s390x`. Official images
-*must* be build on both architectures and they must be build *in
-sequence*, i.e., they can't be build in parallel.
+them are available for the following platforms:
 
-To build a package on an architecture:
+* `linux/amd64`
+* `linux/arm64`
+* `linux/s390x`
 
-```
-DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="<passphrase>" linuxkit pkg push «path-to-package»
-```
+Official images *must* be built for all architectures for which they are available.
 
-`«path-to-package»` is the path to the package's source directory
+Pushing out a package as a maintainer involves two stages:
+
+1. Building and pushing out the platform-specific images
+1. Creating and pushing out the multi-arch manifest, a.k.a. OCI image index
+
+The `linuxkit pkg` command contains automation which performs all of the steps.
+Note that `«path-to-package»` is the path to the package's source directory
 (containing at least `build.yml` and `Dockerfile`). It can be `.` if
 the package is in the current directory.
 
-**Note:** You *must* be logged into hub (`docker login`) and the
-passphrase for the key *must* be supplied as an environment
-variable. The build process has to resort to using `expect` to drive
-`notary` so none of the credentials can be entered interactively.
-
-This will:
-- Build a local images as `linuxkit/<image>:<hash>-<arch>`
-- Push it to hub
-- Sign it with your key
-- Create a manifest called `linuxkit/<image>:<hash>` (note no `-<arch>`)
-- Push the manifest to hub
-- Sign the manifest
-
-If you repeat the same on another architecture, a new manifest will be
-pushed and signed containing the previous and the new
-architecture. The YAML files should consume the package as:
-`linuxkit/<image>:<hash>`.
-
-
-Since it is not very good to have your passphrase in the clear (or
-even stashed in your shell history), we recommend using a password
-manager with a CLI interface, such as LastPass or `pass`. You can then
-invoke the build like this (for LastPass):
-
 ```
-DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE=$(lpass show <key> --password) linuxkit pkg push «path-to-package»
-```
-or alternatively you may add the command to `~/.moby/linuxkit/config.yml` e.g.:
-```
-pkg:
-  content-trust-passphrase-command: "lpass show <key> --password"
+linuxkit pkg push «path-to-package»
 ```
 
+This will do the following:
+
+1. Determine the name and tag for the image as follows:
+   * The tag is from the hash of the git tree for that package. You can see it by doing `linuxkit pkg show-tag «path-to-package»`.
+   * The name for the image is from `«path-to-package»/build.yml`
+   * The organization for the package is given on the command-line, default to `linuxkit`.
+1. Build the package in the given path using your local docker instance for all the platforms in `«path-to-package»/build.yml`
+1. Save the built image in the linuxkit cache
+1. Tag each built image as `«image-name»:«hash»-«arch»`
+1. Create a multi-arch manifest called `«image-name»:«hash»` (note no `-«arch»`)
+1. Push the manifest and all of the images to the hub
+
+Note that for actual release images, these steps normally are performed as part
+of CI, by the merge-to-master process.
+
+#### Prerequisites
+
+* For all of the steps, you *must* be logged into hub (`docker login`).
+
 ### Build packages as a developer
 
-If you want to develop packages or test them locally, it is best to
-override the hub organisation used. You may also want to disable
-signing while developing. A typical example would be:
 
 ```
-linuxkit pkg build -org=wombat -disable-content-trust «path-to-package»
+linuxkit pkg build -org=wombat «path-to-package»
 ```
 
 This will create a local image: `wombat/<image>:<hash>-<arch>` which
@@ -135,7 +341,7 @@ on other systems you can push the image to your hub account and pull
 from a different system by issuing:
 
 ```
-linuxkit pkg build -org=wombat -disable-content-trust push
+linuxkit pkg build -org=wombat push
 ```
 
 This will push both `wombat/<image>:<hash>-<arch>` and
@@ -145,8 +351,45 @@ Finally, if you are tired of the long hashes you can override the hash
 with:
 
 ```
-linuxkit pkg build -org=wombat -disable-content-trust -hash=foo push
+linuxkit pkg build -org=wombat -hash=foo push
 ```
 
 and this will create `wombat/<image>:foo-<arch>` and
 `wombat/<image>:foo` for use in your YAML files.
+
+### Proxies
+
+If you are building packages from behind a proxy, `linuxkit pkg build` respects
+the following environment variables, and will set them as `--build-arg` to
+`docker build` when building a package.
+
+* `http_proxy` / `HTTP_PROXY`
+* `https_proxy` / `HTTPS_PROXY`
+* `ftp_proxy` / `FTP_PROXY`
+* `no_proxy` / `NO_PROXY`
+* `all_proxy` / `ALL_PROXY`
+
+Note that the first four of these are the standard built-in `build-arg` options available
+for `docker build`; see the [docker build documentation](https://docs.docker.com/v17.09/engine/reference/builder/#arg).
+The last, `all_proxy`, is a standard var used for socks proxying. Since it is not built into `docker build`,
+if you want to use it, you will need to add the following line to the dockerfile:
+
+```dockerfile
+ARG all_proxy
+```
+
+LinuxKit does not judge between lower-cased or upper-cased variants of these options, e.g. `http_proxy` vs `HTTP_PROXY`,
+as `docker build` does not either. It just passes them through "as-is".
+
+## Releases
+
+Normally, whenever a package is updated, CI will build and push the package to Docker Hub by calling `linuxkit pkg push`.
+This automatically creates a tag based on the git tree hash of the package's directory.
+For example, the package in `./pkg/init` is tagged as `linuxkit/init:45a1ad5919f0b6acf0f0cf730e9434abfae11fe6`.
+
+In addition, you can release semver tags for packages by adding a tag to the git repository that begins with `pkg-` and is
+followed by a valid semver tag. For example, `pkg-v1.0.0`. This will cause CI to build and push the package to Docker Hub
+with the tag `v1.0.0`.
+
+Pure semver tags, like `v1.0.0`, are not used for package releases. They are used for the linuxkit project itself and to
+publish releases of the `linuxkit` binary.

docs/platform-aws.md

@@ -35,7 +35,7 @@ specified bucket, and create a bootable image from the stored image.
 
 Alternatively, you can use the `AWS_BUCKET` environment variable to specify the bucket name.
 
-**Note:** If the push times out before it finishes, you can use the `-timeout` flag to extend the timeout.
+**Note:** If the push times out before it finishes, you can use the `-timeout` flag to extend the timeout. You may also want to consider passing `-ena` to enable enhanced networking in the AMI.
 
 ```
 linuxkit push aws -bucket bucketname -timeout 1200 aws.raw
@@ -47,7 +47,7 @@ With the image created, we can now create an instance.
 You won't be able to see the serial console output until after it has terminated.
 
 ```
-linuxkit run aws aws
+linuxkit run aws -security-group "<security_group_id>" aws
 ```
 
 You can edit the AWS example to allow you to SSH to your instance in order to use it.

docs/platform-equinixmetal.md

@@ -0,0 +1,142 @@
+# LinuxKit with bare metal on Equinix Metal
+
+[Equinix Metal](http://deploy.equinix.com) is a bare metal hosting provider.
+
+You will need to [create an Equinix Metal account] and a project to
+put this new machine into. You will also need to [create an API key]
+with appropriate read/write permissions to allow the image to boot.
+
+[create an Equinix Metal account]:https://console.equinix.com/sign-up
+[create an API key]:https://deploy.equinix.com/developers/docs/metal/identity-access-management/api-keys/
+
+The `linuxkit run equinixmetal` command can mostly either be configured via
+command line options or with environment variables. see `linuxkit run
+equinixmetal --help` for the options and environment variables.
+
+By default, `linuxkit run` will provision a new machine and remove it
+once you are done. With the `-keep` option the provisioned machine
+will not be removed. You can then use the `-device` option with the
+device ID on subsequent `linuxkit run` invocations to re-use an
+existing machine. These subsequent runs will update the iPXE data so
+you can boot alternative kernels on an existing machine.
+
+There is an example YAML file for [x86_64](../examples/equinixmetal.yml) and
+an additional YAML for [arm64](../examples/equinixmetal.arm64.yml) servers
+which provide both access to the serial console and via ssh and
+configures bonding for network devices via metadata (if supported).
+
+For x86_64 builds for Intel servers we strongly recommend adding
+`ucode: intel-ucode.cpio` to the kernel section in the YAML. This
+updates the Intel CPU microcode to the latest by prepending it to the
+generated initrd file. The `ucode` entry is only recommended when
+booting on baremetal. It should be omitted (but is harmless) when
+building images to boot in VMs.
+
+**Note**: The update of the iPXE configuration sometimes may take some
+time and the first boot may fail. Hitting return on the console to
+retry the boot typically fixes this.
+
+## Boot
+
+LinuxKit on Equinix Metal boots the `kernel+initrd` output from moby via
+[iPXE](https://deploy.equinix.com/developers/docs/metal/operating-systems/custom-ipxe/)
+which also requires a iPXE script. iPXE booting requires a HTTP server
+on which you can store your images. The `-base-url` option specifies
+the URL to a HTTP server from which `<name>-kernel`,
+`<name>-initrd.img`, and `<name>-equinixmetal.ipxe` can be downloaded during
+boot.
+
+If you have your own HTTP server, you can use `linuxkit push equinixmetal`
+to create the files (including the iPXE script) you need to make
+available.
+
+If you don't have a public HTTP server at hand, you can use the
+`-serve` option. This will create a local HTTP server which can either
+be run on another Equinix Metal machine or be made accessible with tools
+like [ngrok](https://ngrok.com/).
+
+For example, to boot the [example](../examples/platform-equinixmetal.yml)
+with a local HTTP server:
+
+```sh
+linuxkit build platform-equinixmetal.yml
+# run the web server
+# run 'ngrok http 8080' in another window
+METAL_AUTH_TOKEN=<API key> METAL_PROJECT_ID=<Project ID> \
+linuxkit run equinixmetal -serve :8080 -base-url <ngrok url> equinixmetal
+```
+
+To boot a `arm64` image for Type 2a machine (`-machine baremetal_2a`)
+you currently need to build using `linuxkit build equinixmetal.yml
+equinixmetal.arm64.yml` and then un-compress both the kernel and the initrd
+before booting, e.g:
+
+```sh
+mv equinixmetal-initrd.img equinixmetal-initrd.img.gz && gzip -d equinixmetal-initrd.img.gz
+mv equinixmetal-kernel equinixmetal-kernel.gz && gzip -d equinixmetal-kernel.gz
+```
+
+The LinuxKit image can then be booted with:
+
+```sh
+METAL_API_TOKEN=<API key> METAL_PROJECT_ID=<Project ID> \
+linuxkit run equinixmetal -machine baremetal_2a  -serve :8080 -base-url -base-url <ngrok url> equinixmetal
+```
+
+Alternatively, `linuxkit push equinixmetal` will uncompress the kernel and
+initrd images on arm machines (or explicitly via the `-decompress`
+flag. There is also a `linuxkit serve` command which will start a
+local HTTP server serving the specified directory.
+
+**Note**: It may take several minutes to deploy a new server. If you
+are attached to the console, you should see the BIOS and the boot
+messages.
+
+
+## Console
+
+By default, `linuxkit run equinixmetal ...` will connect to the
+Equinix Metal
+[SOS ("Serial over SSH") console](https://deploy.equinix.com/developers/docs/metal/resilience-recovery/serial-over-ssh/). This
+requires `ssh` access, i.e., you must have uploaded your SSH keys to
+Equinix Metal beforehand.
+
+You can exit the console vi `~.` on a new line once you are
+disconnected from the serial, e.g. after poweroff.
+
+**Note**: We also require that the Equinix Metal SOS host is in your
+`known_hosts` file, otherwise the connection to the console will
+fail. There is a Equinix Metal SOS host per zone.
+
+You can disable the serial console access with the `-console=false`
+command line option.
+
+
+## Disks
+
+At this moment the Linuxkit server boots from RAM, with no persistent
+storage.  We are working on adding persistent storage support on Equinix Metal.
+
+
+## Networking
+
+On the baremetal type 2a system (arm64 Cavium Thunder X) the network device driver does not get autoloaded by `mdev`. Please add:
+
+```
+  - name: modprobe
+    image: linuxkit/modprobe:<hash>
+    command: ["modprobe", "nicvf"]
+```
+
+to your YAML files before any containers requiring the network to be up, e.g., the `dhcpcd` container.
+
+Some Equinix Metal server types have bonded networks; the `metadata` package has support for setting
+these up, and also for adding additional IP addresses.
+
+
+## Integration services and Metadata
+
+Equinix Metal supports [user state](https://deploy.equinix.com/developers/docs/metal/server-metadata/user-data/)
+during system bringup, which enables the boot process to be more informative about the
+current state of the boot process once the kernel has loaded but before the
+system is ready for login.

docs/platform-hyperkit.md

@@ -20,7 +20,7 @@ The HyperKit backend currently supports booting:
 You need to select the boot method manually using the command line
 options. The default is `kernel+initrd`. `kernel+squashfs` can be
 selected using `-squashfs` and to boot a ISO with EFI you have to
-specify `-iso -uefi`.
+specify `--iso --uefi`.
 
 The `kernel+initrd` uses a RAM disk for the root filesystem. If you
 have RAM constraints or large images we recommend using either the

docs/platform-hyperv.md

@@ -8,7 +8,7 @@ manage the Hyper-V VMs.
 
 Example:
 ```sh
-linuxkit.exe run -disk size=1 linuxkit-efi.iso
+linuxkit.exe run --disk size=1 linuxkit-efi.iso
 ```
 
 The Hyper-V VM, by default, is named after the prefix of the ISO, ie

docs/platform-openstack.md

@@ -11,17 +11,7 @@ Supported (tested) versions of the relevant OpenStack APIs are:
 
 ## Authentication
 
-LinuxKit's support for OpenStack handles two ways of providing the endpoint and authentication details.  You can either set the standard set of environment variables and the commands detailed below will inherit those, or you can explicitly provide them on the command-line as options to `push` and `run`.  The examples below use the latter, but if you prefer the former then you'll need to set the following:
-
-```shell
-OS_USERNAME="admin"
-OS_PASSWORD="xxx"
-OS_TENANT_NAME="linuxkit"
-OS_AUTH_URL="https://keystone.com:5000/v3"
-OS_USER_DOMAIN_NAME=default
-OS_CACERT=/path/to/cacert.pem
-OS_INSECURE=false
-```
+LinuxKit's support for OpenStack includes configuring access to your cloud as detailed in the official [os-client-config](https://docs.openstack.org/os-client-config/latest/user/configuration.html) documentation.
 
 ## Push
 
@@ -40,32 +30,17 @@ Images generated with Moby can be uploaded into OpenStack's image service with `
 
 ```shell
 ./linuxkit push openstack \
-  -authurl=https://keystone.example.com:5000/v3 \
-  -username=admin \
-  -password=XXXXXXXXXXX \
-  -project=linuxkit \
   -img-name=LinuxKitTest
   ./linuxkit.iso
 ```
 
-If successful, this will return the image's UUID.  If you've set your environment variables up as described above, this command can then be simplified:
-
-```shell
-./linuxkit push openstack \
-  -img-name "LinuxKitTest" \
-  ~/Desktop/linuxkitmage.qcow2
-```
-
 ## Run
 
 Virtual machines can be launched using `linuxkit run openstack`.  As an example:
 
 ```shell
 linuxkit run openstack \
-  -authurl https://keystone.example.com:5000/v3 \
-  -username=admin \
-  -password=xxx \
-  -project=linuxkit \
+  -flavor=hotdog
   -keyname=deadline_ed25519 \
   -sec-groups=allow_ssh,nginx \
   -network c5d02c5f-c625-4539-8aed-1dab3aa85a0a \

docs/platform-packet.md

@@ -1,151 +0,0 @@
-# LinuxKit with bare metal on Packet
-
-[Packet](http://packet.net) is a bare metal hosting provider.
-
-You will need to [create a Packet account] and a project to
-put this new machine into. You will also need to [create an API key]
-with appropriate read/write permissions to allow the image to boot.
-
-[create a Packet account]:https://app.packet.net/#/registration/
-[create an API key]:https://help.packet.net/quick-start/api-integrations
-
-Linuxkit is known to boot on the [Type 0] 
-and [Type 1] servers at Packet.
-Support for other server types, including the [Type 2A] ARM server,
-is a work in progress.
-
-[Type 0]:https://www.packet.net/bare-metal/servers/type-0/
-[Type 1]:https://www.packet.net/bare-metal/servers/type-1/
-[Type 2A]:https://www.packet.net/bare-metal/servers/type-2a/
-
-The `linuxkit run packet` command can mostly either be configured via
-command line options or with environment variables. see `linuxkit run
-packet --help` for the options and environment variables.
-
-By default, `linuxkit run` will provision a new machine and remove it
-once you are done. With the `-keep` option the provisioned machine
-will not be removed. You can then use the `-device` option with the
-device ID on subsequent `linuxkit run` invocations to re-use an
-existing machine. These subsequent runs will update the iPXE data so
-you can boot alternative kernels on an existing machine.
-
-There is an example YAML file for [x86_64](../examples/packet.yml) and
-an additional YAML for [arm64](../examples/packet.arm64.yml) servers
-which provide both access to the serial console and via ssh and
-configures bonding for network devices via metadata (if supported).
-
-For x86_64 builds for Intel servers we strongly recommend adding
-`ucode: intel-ucode.cpio` to the kernel section in the YAML. This
-updates the Intel CPU microcode to the latest by prepending it to the
-generated initrd file. The `ucode` entry is only recommended when
-booting on baremetal. It should be omitted (but is harmless) when
-building images to boot in VMs.
-
-**Note**: The update of the iPXE configuration sometimes may take some
-time and the first boot may fail. Hitting return on the console to
-retry the boot typically fixes this.
-
-## Boot
-
-LinuxKit on Packet boots the `kernel+initrd` output from moby via
-[iPXE](https://help.packet.net/technical/infrastructure/custom-ipxe)
-which also requires a iPXE script. iPXE booting requires a HTTP server
-on which you can store your images. The `-base-url` option specifies
-the URL to a HTTP server from which `<name>-kernel`,
-`<name>-initrd.img`, and `<name>-packet.ipxe` can be downloaded during
-boot.
-
-If you have your own HTTP server, you can use `linuxkit push packet`
-to create the files (including the iPXE script) you need to make
-available.
-
-If you don't have a public HTTP server at hand, you can use the
-`-serve` option. This will create a local HTTP server which can either
-be run on another Packet machine or be made accessible with tools
-like [ngrok](https://ngrok.com/).
-
-For example, to boot the [example](../examples/packet.net)
-with a local HTTP server:
-
-```sh
-linuxkit build packet.yml
-# run the web server
-# run 'ngrok http 8080' in another window
-PACKET_API_KEY=<API key> PACKET_PROJECT_ID=<Project ID> \
-linuxkit run packet -serve :8080 -base-url <ngrok url> packet
-```
-
-To boot a `arm64` image for Type 2a machine (`-machine baremetal_2a`)
-you currently need to build using `linuxkit build packet.yml
-packet.arm64.yml` and then un-compress both the kernel and the initrd
-before booting, e.g:
-
-```sh
-mv packet-initrd.img packet-initrd.img.gz && gzip -d packet-initrd.img.gz
-mv packet-kernel packet-kernel.gz && gzip -d packet-kernel.gz
-```
-
-The LinuxKit image can then be booted with:
-
-```sh
-PACKET_API_KEY=<API key> PACKET_PROJECT_ID=<Project ID> \
-linuxkit run packet -machine baremetal_2a  -serve :8080 -base-url -base-url <ngrok url> packet
-```
-
-Alternatively, `linuxkit push packet` will uncompress the kernel and
-initrd images on arm machines (or explicitly via the `-decompress`
-flag. There is also a `linuxkit serve` command which will start a
-local HTTP server serving the specified directory.
-
-**Note**: It may take several minutes to deploy a new server. If you
-are attached to the console, you should see the BIOS and the boot
-messages.
-
-
-## Console
-
-By default, `linuxkit run packet ...` will connect to the
-Packet
-[SOS ("Serial over SSH") console](https://help.packet.net/technical/networking/sos-rescue-mode). This
-requires `ssh` access, i.e., you must have uploaded your SSH keys to
-Packet beforehand.
-
-You can exit the console vi `~.` on a new line once you are
-disconnected from the serial, e.g. after poweroff.
-
-**Note**: We also require that the Packet SOS host is in your
-`known_hosts` file, otherwise the connection to the console will
-fail. There is a Packet SOS host per zone.
-
-You can disable the serial console access with the `-console=false`
-command line option.
-
-
-## Disks
-
-At this moment the Linuxkit server boots from RAM, with no persistent
-storage.  We are working on adding persistent storage support on Packet.
-
-
-## Networking
-
-On the baremetal type 2a system (arm64 Cavium Thunder X) the network device driver does not get autoloaded by `mdev`. Please add:
-
-```
-  - name: modprobe
-    image: linuxkit/modprobe:<hash>
-    command: ["modprobe", "nicvf"]
-```
-
-to your YAML files before any containers requiring the network to be up, e.g., the `dhcpcd` container.
-
-Some Packet server types have bonded networks; the `metadata` package has support for setting
-these up, and also for adding additional IP addresses.
-
-
-## Integration services and Metadata
-
-Packet supports [user state](https://help.packet.net/technical/infrastructure/user-state)
-during system bringup, which enables the boot process to be more informative about the
-current state of the boot process once the kernel has loaded but before the
-system is ready for login.

docs/platform-qemu.md

@@ -24,9 +24,9 @@ specified with `-arch` and currently accepts `x86_64`, `aarch64`, and
 `linuxkit run qemu` can boot in different types of images:
 
 - `kernel+initrd`: This is the default mode of `linuxkit run qemu` [`x86_64`, `arm64`, `s390x`]
-- `kernel+squashfs`: `linuxkit run qemu -squashfs <path to directory>`. This expects a kernel and a squashfs image. [`x86_64`, `arm64`, `s390x`]
-- `iso-bios`: `linuxkit run qemu -iso <path to iso>` [`x86_64`]
-- `iso-efi`: `linuxkit run qemu -iso -uefi <path to iso>`. This looks in `/usr/share/ovmf/bios.bin` for the EFI firmware by default. Can be overwritten with `-fw`. [`x86_64`, `arm64`]
+- `kernel+squashfs`: `linuxkit run qemu --squashfs <path to directory>`. This expects a kernel and a squashfs image. [`x86_64`, `arm64`, `s390x`]
+- `iso-bios`: `linuxkit run qemu --iso <path to iso>` [`x86_64`]
+- `iso-efi`: `linuxkit run qemu --iso --uefi <path to iso>`. This looks in `/usr/share/ovmf/bios.bin` for the EFI firmware by default. Can be overwritten with `-fw`. [`x86_64`, `arm64`]
 - `qcow-bios`: `linuxkit run qemu disk.qcow2` [`x86_64`]
 - `raw-bios`:  `linuxkit run qemu disk.img` [`x86_64`]
 - `aws`: `linuxkit run qemu disk.img` boots a raw AWS disk image. [`x86_64`]

docs/platform-rpi3.md

@@ -70,4 +70,11 @@ LinuxKit YAML file:
     command: ["modprobe", "smsc95xx"]
 ```
 
+For Raspberry Pi 3b+ use:
+```
+  - name: netdev
+    image: linuxkit/modprobe:<hash>
+    command: ["modprobe", "lan78xx"]
+```
+
 **TODO:** Figure out why mdev is not loading the driver.

docs/platform-scaleway.md

@@ -0,0 +1,62 @@
+# Using LinuxKit on Scaleway
+
+This is a quick guide to run LinuxKit on Scaleway (only VPS x86_64 for now)
+
+## Setup
+
+You must create a Scaleway API Token (combination of Access and Secret Key), available at [Scaleway Console](https://console.scaleway.com/account/credentials), first.
+Then you can use it either with the `SCW_ACCESS_KEY` and `SCW_SECRET_KEY` environment variables or the `-access-key` and `-secret-key` flags
+of the `linuxkit push scaleway` and `linuxkit run scaleway` commands.
+
+In addition, Organization ID value has to be set, either with the `SCW_DEFAULT_ORGANIZATION_ID` environment variable or the `-organization-id` command line flag.
+
+The environment variable `SCW_DEFAULT_ZONE` is used to set the zone (there is also the `-zone` flag)
+
+## Build an image
+
+Scaleway requires a `iso-efi` image. To create one:
+
+```
+$ linuxkit build -format iso-efi examples/scaleway.yml
+```
+
+### Changes needed in the yaml
+
+* You have to set `root=/dev/vda` in the `cmdline` to have the right device set on boot
+* The metadata package is not only used to set the metadata, but also to signal Scaleway that the instance has booted. So it is encouraged to use it (dhcpcd must be set before)
+
+## Push image
+
+You have to do `linuxkit push scaleway scaleway.iso` to upload it to your Scaleway images.
+By default the image name is the name of the ISO file without the extension.
+It can be overidden with the `-img-name` flag or the `SCW_IMAGE_NAME` environment variable.
+
+**Note 1:** If an image (and snapshot) of the same name exists, it will be replaced.
+
+**Note 2:** The image is zone specific: if you create an image in `par1` you can't use is in `ams1`.
+
+### Push process
+
+Building a Scaleway image have a special process. Basically:
+
+* Create an `image-builder` instance with an additional volume, based on Ubuntu Bionic (only x86_64 for now)
+* Copy the ISO image on this instance
+* Use `dd` to write the image on the additional volume (`/dev/vdb` by default)
+* Terminate the instance, create a snapshot, and create an image from the snapshot
+
+**Note 1:** An image is linked to a snapshot, so you can't delete a snapshot before the image.
+
+**Note 2:** You can specify an already running instance to act as the image builder with the `-instance-id` flag. But if you don't specify the `-no-clean` flag it will be destroyed upon completion.
+
+## Create an instance and connect to it
+
+With the image created, we can now create an instance.
+
+```
+linuxkit run scaleway scaleway
+```
+
+By default, the instance name is `linuxkit`. It can be overidden with the `-instance-name` flag.
+If you don't set the `-no-attach` flag, you will be connected to the serial port.
+
+You can edit the Scaleway example to allow you to SSH to your instance in order to use it.

docs/platform-vbox.md

@@ -20,11 +20,20 @@ stdio, providing interactive access to the VM.
 ## Disks
 
 The Virtualbox backend support configuring a persistent disk using the
-standard `linuxkit` `-disk` syntax.  Multiple disks are
+standard `linuxkit` `-disk` syntax. Multiple disks are
 supported and can be created in `raw` format; other formats that VirtualBox
-supports can be attached
+supports can be attached. Note that additional drives are attached to the
+SATA Controller, unlike the VM disk which is on the IDE Controller.
 
 ## Networking
 
-You can select the networking mode, which defaults to the standard `nat`, but
-some networking modes may require additional configuration.
+You can select the networking mode, which defaults to the standard `nat`, by using the
+`-networking` command-line option. Some networking modes (`hostonly`, `bridge`) will require 
+the additional `adapter` parameter to the `-networking` option:
+
+~~~
+-networking hostonly,adapter=vboxnet0
+~~~
+
+You can specify more than one `-networking` option to setup multiple adapters. It is
+recommended to setup the first adapter as `nat`.

docs/platform-virtualization-framework.md

@@ -0,0 +1,205 @@
+# LinuxKit with Virtualization.Framework (macOS)
+
+We recommend using LinuxKit in conjunction with
+[Docker for Mac](https://docs.docker.com/docker-for-mac/install/). For
+the time being it's best to be on the latest edge release. `linuxkit
+run` uses [Virtualization.Framework](https://developer.apple.com/documentation/virtualization) and
+[VPNKit](https://github.com/moby/vpnkit) and the edge release ships
+with updated versions of both.
+
+Alternatively, you can install Virtualization.Framework and VPNKit standalone and use it without Docker for Mac.
+
+Virtualization.Framework is enabled on macOS only when built with CGO enabled.
+
+## Boot
+
+The Virtualization.Framework backend currently supports booting:
+- `kernel+initrd` output from `linuxkit build`.
+- `kernel+squashfs` output from `linuxkit build`.
+- EFI ISOs using the EFI firmware.
+
+You need to select the boot method manually using the command line
+options. The default is `kernel+initrd`. `kernel+squashfs` can be
+selected using `-squashfs` and to boot a ISO with EFI you have to
+specify `--iso --uefi`.
+
+The `kernel+initrd` uses a RAM disk for the root filesystem. If you
+have RAM constraints or large images we recommend using either the
+`kernel+squashfs` or the EFI ISO boot.
+
+## Console
+
+With `linuxkit run` on Virtualization.Framework the serial console is redirected to
+stdio, providing interactive access to the VM. The output of the VM
+can be re-directed to a file or pipe, but then stdin is not available.
+Virtualization.Framework does not provide a console device.
+
+
+## Disks
+
+The Virtualization.Framework backend support configuring a persistent disk using the
+standard `linuxkit` `-disk` syntax.  Multiple disks are
+supported and the disks are in raw format.
+
+## Power management
+
+Virtualization.Framework sends an ACPI power event when it receives SIGTERM to allow the VM to
+shut down properly. The VM has to be able to receive ACPI events to initiate the
+shutdown.  This is provided by the [`acpid` package](../pkg/acpid). An example
+is available in the [Docker for Mac example](../examples/docker-for-mac.yml).
+
+## Networking
+
+By default, `linuxkit run` creates a VM with a single network
+interface which, logically, is attached to a L2 bridge. The bridge
+also has the VM used by Docker for Mac attached to it. This means that
+the LinuxKit VMs, created with `linuxkit run`, can be accessed from
+containers running on Docker for Mac.
+
+The LinuxKit VMs have IP addresses on the `192.168.65.0/24` subnet
+assigned by a DHCP server part of VPNKit. `192.168.65.1` is reserved
+for VPNKit as the default gateway and `192.168.65.2` is used by the
+Docker for Mac VM.
+
+By default, LinuxKit VMs get incrementally increasing IP addresses,
+but you can assign a fixed IP address with `linuxkit run -ip`. It's
+best to choose an IP address from the DHCP address range above, but
+care must be taken to avoid clashes of IP address.
+
+*NOTE:* The LinuxKit VMs can *not* be directly accessed by IP address
+from the host.  Enabling this would require use of the macOS `vmnet`
+framework, which requires the VMs to run as `root`.  We don't consider
+this option palatable, and provide alternative options to access the
+VMs over the network below.
+
+
+### Accessing network services
+
+Virtualization.Framework offers a number of ways for accessing network services
+running inside the LinuxKit VM from the host. These depend on the
+networking mode selected via `-networking`. The default mode is
+`vmnet`, where it sets up a network bridge. We intend to add support for
+`docker-for-mac`, where the same VPNkit instance is shared between
+LinuxKit VMs and the VM running as part of Docker for Mac, in the future.
+
+#### Access from the Docker for Mac VM (`-networking docker-for-mac`)
+
+The simplest way to access networking services exposed by a LinuxKit
+VM is to use a Docker for Mac container. For example, to access an ssh
+server in a LinuxKit VM, create a ssh client container from:
+
+```
+FROM alpine:edge
+RUN apk add --no-cache openssh-client
+```
+
+and then run
+
+```
+docker build -t ssh .
+docker run --rm -ti -v ~/.ssh:/root/.ssh  ssh ssh <IP address of VM>
+```
+
+#### Forwarding ports with `socat`  (`-networking docker-for-mac`)
+
+A `socat` container on Docker for Mac can be used to proxy between the
+LinuxKit VM's ports and localhost.  For example, to expose the redis
+port from the [RedisOS example](../examples/redis-os.yml), use this
+Dockerfile:
+
+```
+FROM alpine:edge
+RUN apk add --no-cache socat
+ENTRYPOINT [ "/usr/bin/socat" ]
+```
+and then:
+```
+docker build -t socat .
+docker run --rm -t -d -p 6379:6379 socat tcp-listen:6379,reuseaddr,fork tcp:<IP address of VM>:6379
+```
+
+#### Port forwarding with VPNKit (`-networking docker-for-mac`)
+
+There is **experimental** support for exposing selected ports of the
+guest on `localhost` using the `-publish` command line option. For
+example, using `-publish 2222:22/tcp` exposes the guest TCP port 22 on
+localhost on port 2222. Multiple `-publish` options can be
+specified. For example, the image build from the [`sshd
+example`](../examples/sshd.yml) can be started with:
+
+```
+linuxkit run -publish 2222:22/tcp sshd
+```
+
+and then you can log into the LinuxKit VM with `ssh -p 2222
+root@localhost`.
+
+Note, this mode is **experimental** and may cause the VPNKit instance
+shared with Docker for Mac being confused about which ports are
+currently in use, in particular if the LinuxKit VM does not exit
+gracefully. This can typically be fixed by restarting Docker for Mac.
+
+
+#### Port forwarding with VPNKit (`-networking vpnkit`)
+
+An alternative to the previous method is to start your own copy of
+`vpnkit` (or connect to an already running instance). This can be done
+using the `-networking vpnkit` command line option.
+
+VPNKit uses a 9P mount in `/port` for coordination between
+components. The first VM on a VPNKit instance currently needs mount
+the 9P filesystem and also needs to run the `vpnkit-forwarder` service
+to enable port forwarding to localhost.  A full example with `vpnkit`
+forwarding of `sshd` is available in
+[examples/vpnkit-forwarder.yml](/examples/vpnkit-forwarder.yml).
+
+To run this example with its own instance of VPNKit, use:
+
+```
+linuxkit run -networking vpnkit -publish 2222:22/tcp vpnkit-forwarder
+```
+
+You can then access it via:
+
+```
+ssh -p 2222 root@localhost
+```
+
+More details about the VPNKit forwarding mechanism is available in the
+[VPNKit
+documentation](https://github.com/moby/vpnkit/blob/master/docs/ports.md#signalling-from-the-vm-to-the-host).
+
+
+## Integration services and Metadata
+
+There are no special integration services available for Virtualization.Framework, but
+there are a number of packages, such as `vsudd`, which enable
+tighter integration of the VM with the host (see below).
+
+The Virtualization.Framework backend also allows passing custom userdata into the
+[metadata package](./metadata.md) using either the `-data` or `-data-file` command-line
+option. This attaches a CD device with the data on.
+
+
+### `vsudd` unix domain socket forwarding
+
+The [`vsudd` package](/pkg/vsudd) provides a daemon that exposes unix
+domain socket inside the VM to the host via virtio or Hyper-V sockets.
+With Virtualization.Framework, the virtio sockets can be exposed as unix domain
+sockets on the host, enabling access to other daemons, like
+`containerd` and `dockerd`, from the host.  An example configuration
+file is available in [examples/vsudd-containerd.yml](/examples/vsudd-containerd.yml).
+
+After building the example, run it with `linuxkit run virtualization.framework
+-vsock-ports 2374 vsudd`. This will create a unix domain socket in the state directory that maps to the `containerd` control socket. The socket is called `guest.00000946`.
+
+If you install the `ctr` tool on the host you should be able to access the
+`containerd` running in the VM:
+
+```
+$ go get -u -ldflags -s github.com/containerd/containerd/cmd/ctr
+...
+$ ctr -a vsudd-state/guest.00000946 list
+ID        IMAGE     PID       STATUS
+vsudd               466       RUNNING
+```

docs/releasing.md

@@ -0,0 +1,88 @@
+# Making a LinuxKit release
+
+This document describes the steps to make a LinuxKit release. A
+LinuxKit release consists of:
+- A git tag of the form vX.Y on a specific commit.
+- Packages on Docker hub, tagged with the release tag.
+- All sample `YAML` files updated to use the release packages
+- `linuxkit` binaries for all supported architectures.
+- Changelog entry
+
+Note, we explicitly do not tag kernel images with LinuxKit release
+tags as we encourage users to stay current with the kernel
+releases. We also do not tag test and `mkimage` packages as these are
+not end-user facing.
+
+
+## Pre-requisites
+
+Releases can be done by any maintainer. Maintainers need to have
+access to build machines for all architectures support by LinuxKit and
+signing keys set up to sign Docker hub images.
+
+
+## Release preparation
+
+The release preparation is by far the most time consuming task as it
+involves updating all packages and YAML files.
+
+The release preparation is performed on a branch of your up-to-date
+LinuxKit clone. This document assumes that your clone of the LinuxKit
+repository is available as the `origin` remote in your local `git`
+clone (in my setup the official LinuxKit repository is available as
+`upstream` remote). If your setup is different, you may have to adjust
+some of the commands below.
+
+As a starting point you have to be on the update to date master branch
+and be in the root directory of your local git clone. You should also
+have the same setup on all build machines used.
+
+### Update `linuxkit/alpine`
+
+This step is not necessarily required if the alpine base image has
+recently been updated, but it is good to pick up any recent bug
+fixes. Follow the process in [alpine-base-update.md](./alpine-base-update.md)
+
+There are several important notes to consider when updating alpine base:
+
+* `LK_BRANCH` is set to `rel_$LK_RELEASE`, when cutting a release, for e.g. `LK_BRANCH=rel_v0.9`
+* It not necessarily required to update the alpine base image if it has recently been updated, but it is good to pick up any recent bug
+fixes. However, you do need to update the tools, packages and tests.
+* Releases are a particularly good time to check for updates in wrapped external dependencies, as highlighted in [alpine-base-update.md#External Tools](./alpine-base-update.md#External_Tools)
+
+### Final preparation steps
+
+- Update AUTHORS by running `./scripts/generate-authors.sh`
+- Update the `VERSION` variable in the top-level `Makefile`
+- Create an entry in `CHANGELOG.md`. Take a look at `git log v0.3..HEAD` and pick interesting updates (of course adjust `v0.3` to the previous version).
+- Create a PR with your changes.
+
+
+## Releasing
+
+Once the PR is merged we can do the actual release.
+
+- Update your local git clone to the lastest
+- Identify the merge commit for your PR and tag it and push it to the main LinuxKit repository (remote `upstream` in my case):
+
+```
+git tag $LK_RELEASE master
+git push upstream $LK_RELEASE
+```
+
+Then head over to GitHub and look at the `Releases` tab. You should see the new tag. Edit it:
+- Add the changelog message
+- Head over to the Circle CI page of the master build (try the Circle CI badge in the top level `README.md`)
+- Download the artefacts and SHA256 sums file.
+- Add the downloaded binaries to the release page (drag-and-drop below the editor window)
+- Add the `sha256` sums to the release notes on the release page
+
+Hit the `Publish release` button.
+
+This completes the release, but you are not done, one more step is required.
+
+## Post release
+
+Create a PR which bumps the version number in the top-level `Makefile`
+to `$LK_RELEASE+` to make sure that the version reported by `linuxkit
+version` gets updated.

docs/reproducible-builds.md

@@ -0,0 +1,71 @@
+# Reproducible builds
+
+We aim to make the outputs of `linuxkit build` reproducible, i.e. the
+build artefacts should be bit-by-bit identical copies if invoked with
+the same inputs and run with the same version of the `linuxkit`
+command. See [this
+document](https://reproducible-builds.org/docs/buy-in/) on why this
+matters.
+
+_Note, we do not (yet) aim to make `linuxkit pkg build` builds
+reproducible._
+
+
+## Current status
+
+Currently, the following output formats provide reproducible builds:
+- `tar` (Tested as part of the CI)
+- `tar-kernel-initrd`
+- `docker`
+- `kernel+initrd` (Tested as part of the CI)
+
+
+## Details
+
+In general, `linuxkit build` lends itself for reproducible
+builds. LinuxKit packages, used during `linuxkit build`, are (signed)
+docker images. Packages are tagged with the content hash of the source
+code (and optionally release version) and are typically only updated
+if the source of the package changed (in which case the tag
+changes). For all intents and purposes, when pulled by tag, the
+contents of a packages should be bit-by-bit identical. Alternatively,
+the digest of the package, in which case, the pulled image will always
+be the same.
+
+The first phase of the `linuxkit build` mostly untars and retars the
+images of the packages to produce an tar file of the root filesystem.
+This then serves as input for other output formats. During this first
+phase, there are a number of things to watch out for to generate
+reproducible builds:
+
+- Timestamps of generated files. The `docker export` command, as well
+  as `linuxkit build` itself, creates a small number of files. The
+  `ModTime` for these files needs to be clamped to a fixed date
+  (otherwise the current time is used). Use the `defaultModTime`
+  variable to set the `ModTime` of created files to a specific time.
+- Generated JSON files. `linuxkit build` generates a number of JSON
+  files by marshalling Go `struct` variables. Examples are the OCI
+  specification `config.json` and `runtime.json` files for
+  containers. The default Go `json.Marshal()` function seems to do a
+  reasonable good job in generating reproducible output from internal
+  structures, including for JSON objects. However, during `linuxkit
+  build` some of the OCI runtime spec fields are generated/modified
+  and care must be taken to ensure consistent ordering. For JSON
+  arrays (Go slices) it is best to sort them before Marshalling them.
+
+Reproducible builds for the first phase of `linuxkit build` can be
+tested using `-output tar` and comparing the output of subsequent
+builds with tools like `diff` or the excellent
+[`diffoscope`](https://diffoscope.org/).
+
+The second phase of `linuxkit build` converts the intermediary `tar`
+format into the desired output format. Making this phase reproducible
+depends on the tools used to generate the output.
+
+Builds, which produce ISO formats should probably be converted to use
+[`go-diskfs`](https://github.com/diskfs/go-diskfs) before attempting
+to make them reproducible.
+
+For ideas on how to make the builds for other output formats
+reproducible, see [this
+page](https://reproducible-builds.org/docs/system-images/).

docs/sbom.md

@@ -0,0 +1,72 @@
+# Software Bill-of-Materials
+
+LinuxKit bootable images are composed of existing OCI images.
+OCI images, when built, often are scanned to create a
+software bill-of-materials (SBoM). The buildkit builder
+system itself contains the [ability to integrate SBoM scanning and generation into the build process](https://docs.docker.com/build/attestations/sbom/).
+
+When LinuxKit composes an operating system image using `linuxkit build`,
+it will, by default, combine the SBoMs of all the OCI images used to create
+the final image.
+
+It looks for SBoMs in the following locations:
+
+* [image attestation storage](https://docs.docker.com/build/attestations/attestation-storage/)
+
+Future support for [OCI Image-Spec v1.1 Artifacts](https://github.com/opencontainers/image-spec)
+is under consideration, and will be reviewed when it is generally available.
+
+When building packages with `linuxkit pkg build`, it also has the ability to generate an SBoM for the
+package, which later can be consumed by `linuxkit build`.
+
+## Consuming SBoM From Packages
+
+When `linuxkit build` is run, it does the following for dealing with SBoMs:
+
+1. For each OCI image that it processes:
+   1. check if the image contains an SBoM attestation; it not, skip this step.
+   1. Retrieve the SBoM attestation.
+1. After generating the root filesystem, combine all of the individual SBoMs into a single unified SBoM.
+1. Save the output single SBoM into the root of the image as `sbom.spdx.json`.
+
+Currently, only SPDX json format is supported.
+
+### SBoM Scanner and Output Format
+
+By default, linuxkit combines the SBoMs into a file with output format SPDX json,
+and the file saved to the filename `sbom.spdx.json`.
+
+In addition, in order to assist with reproducible builds, the creation date/time of the SBoM is
+a fixed date/time set by linuxkit, rather than the current date/time. Note, however, that even
+with a fixed date/time, reproducible builds depends on reproducible SBoMs on the underlying container images.
+This is not always the case, as the unique IDs for each package and file might be deterministic, but it might not.
+
+This can be overridden by using the CLI flags:
+
+* `--no-sbom`: do not find and consolidate the SBoMs
+* `--sbom-output <filename>`: the filename to save the output to in the image.
+* `--sbom-current-time true|false`: whether or not to use the current time for the SBoM creation date/time (default `false`)
+
+### Disable SBoM for Images
+
+To disable SBoM generation when running `linuxkit build`, use the CLI flag `--sbom false`.
+
+## Generating SBoM For Packages
+
+When `linuxkit pkg build` is run, by default it enables generating an SBoM using the
+[SBoM generating capabilities of buildkit](https://www.docker.com/blog/generate-sboms-with-buildkit/).
+This means that it inherits all of those capabilities as well, and saves the SBoM in the same location,
+as an attestation on the image.
+
+### SBoM Scanner
+
+By default, buildkit runs [syft](http://hub.docker.com/r/anchore/syft) with output format SPDX json,
+specifically via its integration image [buildkit-syft-scanner](docker.io/docker/buildkit-syft-scanner).
+You can select a different image to run a scanner, provided it complies with the
+[buildkit SBoM protocol](https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md),
+by passing the CLI flag `--sbom-scanner <image>`.
+
+### Disable SBoM for Packages
+
+To disable SBoM generation when running `linuxkit pkg build`, use the CLI flag `--sbom-scanner=false`.
+

docs/security.md

@@ -50,8 +50,6 @@ and namespaced separately from the host as appropriate.
 LinuxKit's build process heavily leverages Docker images for packaging. Of note, all intermediate build images
 are referenced by digest to ensures reproducibility across LinuxKit builds. Tags are mutable, and thus subject to override
 (intentionally or maliciously) - referencing by digest mitigates classes of registry poisoning attacks in LinuxKit's buildchain.
-Certain images, such as the kernel image, will be signed by LinuxKit maintainers using [Docker Content Trust](https://docs.docker.com/engine/security/trust/content_trust/),
-which guarantees authenticity, integrity, and freshness of the image.
 
 Moreover, LinuxKit's build process leverages [Alpine Linux's](https://alpinelinux.org/) hardened userspace tools such as
 Musl libc, and compiler options that include `-fstack-protector` and position-independent executable output. Go binaries

docs/signing.md

@@ -1,49 +0,0 @@
-# Signing LinuxKit Hub Images
-
-We sign and verify LinuxKit component images, such as `linuxkit/kernel`, using [Notary](https://github.com/docker/notary).
-
-This document details the process for setting this up, intended for maintainers.
-
-## Initialize a New Repository
-
-Let's say we're publishing a new `linuxkit/foo` image that we want to sign and verify in LinuxKit.
-We first need to initialize the Notary repository:
-
-```
-notary -s https://notary.docker.io -d ~/.docker/trust init -p docker.io/linuxkit/foo
-```
-
-This command will generate some private keys in `~/.docker/trust` and ask you for passphrases such that they are encrypted at rest.
-All linuxkit repositories are currently using the same root key so we can pin trust on key ID `1908a0cf4f55710138e63f65ab2a97e8fa3948e5ca3b8857a29f235a3b61ea1b`.
-
-We'll also let the notary server take control of the snapshot key, for easier delegation collaboration:
-```
-notary -s https://notary.docker.io -d ~/.docker/trust key rotate docker.io/linuxkit/foo snapshot -r
-```
-
-## Add maintainers to delegation roles:
-
-Maintainers are to sign with `delegation` keys, which are adminstered by a non-root key.
-Thusly, they are easily rotated without having to bring the root key online.
-Additionally, maintainers can be added to separate roles for auditing purposes: the current setup is to add maintainers to both the `targets/releases` role that is intended
-for release consumption, as well as an individual `targets/<maintainer_name>` role for auditing.
-Docker will automatically sign into both roles when pushing with Docker Content Trust.
-
-Here's what the command looks like to add all maintainers to the `targets/releases` role:
-```
-notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/releases alice.crt bob.crt charlie.crt --all-paths
-```
-
-Here's what the commands look like to add all maintainers to their individually named roles:
-```
-notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/alice alice.crt --all-paths
-notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/bob bob.crt --all-paths
-notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/charlie charlie.crt --all-paths
-```
-
-## Maintainers import their private keys
-
-It's important that each maintainer imports their private key into Docker's key storage, so Docker can use it to sign:
-```
-notary -d ~/.docker/trust key import alice.key -r user
-```

docs/testing.md

@@ -50,7 +50,7 @@ You must copy an existing `group.sh` in to this folder and adjust as required or
 [example](https://github.com/linuxkit/rtf/tree/master/etc/templates/group.sh)
 
 To write your test, create a folder within the group using the `000_name` format as described above.
-You should then copy an existing `test.sh` in to this directory and amdend it,
+You should then copy an existing `test.sh` in to this directory and amend it,
 or start from an [example](http://github.com/linuxkit/rtf/tree/master/etc/templates/test.sh)
 
 If your test can only be run when certain conditions are met, you should consider adding a label to

docs/troubleshooting.md

@@ -0,0 +1,36 @@
+# Troubleshooting
+
+This document contains a list of known issues related to using, building or testing linuxkit.
+
+## Images
+
+## Packages
+
+### Invalid MediaType
+
+**Problem**
+
+```
+Error: error building and pushing "linuxkit/mkimage-iso-efi-initrd:0e66171ffde9bb735b0e014f811f9626fc8b9bc9": PUT https://index.docker.io/v2/linuxkit/mkimage-iso-efi-initrd/manifests/0e66171ffde9bb735b0e014f811f9626fc8b9bc9: MANIFEST_INVALID: manifest invalid; if present, mediaType in image index should be 'application/vnd.oci.image.index.v1+json' not 'application/vnd.docker.distribution.manifest.list.v2+json'
+```
+
+The above message is caused by registries, notably docker hub, refusing to accept indexes with the
+docker media type of `application/vnd.docker.distribution.manifest.list.v2+json`, rather than the OCI
+one `application/vnd.oci.image.index.v1+json`.
+
+Linuxkit _does_ use the OCI media type, however, if the image _already_ exists in the registry, linuxkit will
+pull the index down, update it, and push it back up. The above error occurs because the index that exists in
+the hub, the one that is pulled down, has the older media type, from when the registry accepted it.
+
+**Solution**
+
+The solution is to force an entirely new build, which will generate the images and index with the correct media
+type.
+
+```
+linuxkit pkg build --force <path>
+linuxkit pkg push <path>
+```
+
+## Testing
+

docs/vendoring.md

@@ -2,22 +2,24 @@ Vendoring
 =========
 
 The Go code in this repo depends on a number of Go libraries.
-These are vendored in to the `src/cmd/linuxkit/vendor` directory using [`vndr`](https://github.com/lk4d4/vndr)
-The `vendor.conf` file contains a list of the repositories and the git SHA or branch name that should be vendored
+These are vendored in to the `src/cmd/linuxkit/vendor` directory using [go modules](https://golang.org/ref/mod)
 
 ## Updating dependencies
 
-Update `src/cmd/linuxkit/vendor.conf` with the dependency that you would like to add.
-Details of usage of the `vndr` tool and the format of `vendor.conf` can be found [here](https://github.com/LK4D4/vndr/blob/master/README.md)
+Go modules should install any required dependencies to `go.mod` and `go.sum` when running normal go commands such as `go build`,
+`go vet`, etc. To install specific versions, use `go get <dependency>@<reference>`.
 
-Once done, you must run the `vndr` tool to add the necessary files to the `vendor` directory.
-The easiest way to do this is in a container.
+See the [go modules](https://golang.org/ref/mod) documentation for more information.
 
-Currently if updating `github.com/moby/tool` it is also necessary to
-update `src/cmd/linuxkit/build.go` manually after updating `vendor.conf`:
+LinuxKit vendors all dependencies to make it completely self-contained. Once `go.mod` is up to date,
+you must update the dependencies, either using your local go toolchain or in a container.
 
-    hash=$(awk '/^github.com\/moby\/tool/ { print $2 }' src/cmd/linuxkit/vendor.conf)
-    curl -fsSL -o src/cmd/linuxkit/build.go https://raw.githubusercontent.com/moby/tool/${hash}/cmd/moby/build.go
+## Updating locally
+
+To vendor all dependencies:
+
+1. `cd src/cmd/linuxkit`
+1. Run `go mod vendor`
 
 ## Updating in a container
 
@@ -27,39 +29,7 @@ To update all dependencies:
 docker run -it --rm \
 -v $(pwd):/go/src/github.com/linuxkit/linuxkit \
 -w /go/src/github.com/linuxkit/linuxkit/src/cmd/linuxkit \
---entrypoint /go/bin/vndr \
-linuxkit/go-compile:a8bffe875268a973ea82e5937b0fb23a5b08cc79
-```
-
-To update a single dependency:
-
-```
-docker run -it --rm \
--v $(pwd):/go/src/github.com/linuxkit/linuxkit \
--w /go/src/github.com/linuxkit/linuxkit/src/cmd/linuxkit \
---entrypoint /go/bin/vndr \
-linuxkit/go-compile:a8bffe875268a973ea82e5937b0fb23a5b08cc79
-github.com/docker/docker
-```
-
-## Updating locally
-
-First you must install `vndr` and ensure that `$GOPATH/bin` is on your `$PATH`
-
-```
-go get -u github.com/LK4D4/vndr
-```
-
-To update all dependencies:
-
-```
-cd src/cmd/linuxkit
-vndr
-```
-
-To update a single dependency:
-
-```
-cd /src/cmd/linuxkit
-vndr github.com/docker/docker
+--entrypoint=go
+linuxkit/go-compile:7b1f5a37d2a93cd4a9aa2a87db264d8145944006
+mod vendor
 ```

docs/yaml.md

@@ -0,0 +1,394 @@
+# Configuration Reference
+
+The `linuxkit build` command assembles a set of containerised components into in image. The simplest
+type of image is just a `tar` file of the contents (useful for debugging) but more useful
+outputs add a `Dockerfile` to build a container, or build a full disk image that can be
+booted as a linuxkit VM. The main use case is to build an assembly that includes
+`containerd` to run a set of containers, but the tooling is very generic.
+
+The yaml configuration specifies the components used to build up an image . All components
+are downloaded at build time to create an image. The image is self-contained and immutable,
+so it can be tested reliably for continuous delivery.
+
+Components are specified as Docker images which are pulled from a registry during build if they
+are not available locally. See [image-cache](./image-cache.md) for more details on local caching.
+The Docker images are optionally verified with Docker Content Trust.
+For private registries or private repositories on a registry credentials provided via
+`docker login` are re-used.
+
+## Sections
+
+The configuration file is processed in the order `kernel`, `init`, `onboot`, `onshutdown`,
+`services`, `files`, `volumes`. Each section adds files to the root file system. Sections may be omitted.
+
+Each container that is specified is allocated a unique `uid` and `gid` that it may use if it
+wishes to run as an isolated user (or user namespace). Anywhere you specify a `uid` or `gid`
+field you specify either the numeric id, or if you use a name it will refer to the id allocated
+to the container with that name.
+
+```
+services:
+  - name: redis
+    image: redis:latest
+    uid: redis
+    gid: redis
+    binds:
+     - /etc/redis:/etc/redis
+files:
+  - path: /etc/redis/redis.conf
+    contents: "..."
+    uid: redis
+    gid: redis
+    mode: "0600"
+```
+
+### `kernel`
+
+The `kernel` section is only required if booting a VM. The files will be put into the `boot/`
+directory, where they are used to build bootable images.
+
+The `kernel` section defines the kernel configuration. The `image` field specifies the Docker image,
+which should contain a `kernel` file that will be booted (eg a `bzImage` for `amd64`) and a file
+called `kernel.tar` which is a tarball that is unpacked into the root, which should usually
+contain a kernel modules directory. `cmdline` specifies the kernel command line options if required.
+
+The contents of `cmdline` are passed to the kernel as-is. There are several special values that are
+used to control the behaviour of linuxkit packages. See [kernel command line options](../docs/cmdline.md).
+
+To override the names, you can specify the kernel image name with `binary: bzImage` and the tar image
+with `tar: kernel.tar` or the empty string or `none` if you do not want to use a tarball at all.
+
+Kernel packages may also contain a cpio archive containing CPU microcode which needs prepending to
+the initrd. To select this option, recommended when booting on bare metal, add `ucode: intel-ucode.cpio`
+to the kernel section.
+
+### `init`
+
+The `init` section is a list of images that are used for the `init` system and are unpacked directly
+into the root filesystem. This should bring up `containerd`, start the system and daemon containers,
+and set up basic filesystem mounts. in the case of a LinuxKit system. For ease of
+modification `runc` and `containerd` images, which just contain these programs are added here
+rather than bundled into the `init` container.
+
+### `onboot`
+
+The `onboot` section is a list of images. These images are run before any other
+images. They are run sequentially and each must exit before the next one is run.
+These images can be used to configure one shot settings. See [Image
+specification](#image-specification) for a list of supported fields.
+
+### `onshutdown`
+
+This is a list of images to run on a clean shutdown. Note that you must not rely on these
+being run at all, as machines may be be powered off or shut down without having time to run
+these scripts. If you add anything here you should test both in the case where they are
+run and when they are not. Most systems are likely to be "crash only" and not have any setup here,
+but you can attempt to deregister cleanly from a network service here, rather than relying
+on timeouts, for example.
+
+### `services`
+
+The `services` section is a list of images for long running services which are
+run with `containerd`.  Startup order is undefined, so containers should wait
+on any resources, such as networking, that they need.  See [Image
+specification](#image-specification) for a list of supported fields.
+
+### `volumes`
+
+The volumes section is a list of named volumes that can be used by other containers,
+including those in `services`, `onboot` and `onshutdown`. The volumes are created in a directory
+chosen by linuxkit at build-time. The volumes then can be referenced by other containers and
+mounted into them.
+
+Volumes normally are blank directories. If an image is provided, the contents of that image
+will be used to populate the volume.
+
+The `volumes` section can declare a volume to be read-write or read-only. If the volume is read-write,
+a volume that is mounted into a container can be mounted read-only or read-write. If the volume is read-only,
+it can be mounted into a container read-only; attempting to do so read-write will generate a build-time error.
+By default, volumes are created read-write, and are mounted read-write.
+
+Volume names **must** be unique, and must contain only lower-case alphanumeric characters, hyphens, and
+underscores.
+
+Sample `volumes` section:
+
+```yml
+volumes:
+- name: vola
+  image: alpine:latest
+  readonly: true
+- name: volb
+  image: alpine:latest
+  readonly: false
+- name: volc
+  readonly: false
+```
+
+In the above example:
+
+* `vola` is populated by the contents of `alpine:latest` and is read-only.
+* `volb` is populated by the contents of `alpine:latest` and is read-write.
+* `volc` is an empty volume and is read-write.
+
+Sample usage of volumes in `services` section:
+
+```yml
+services:
+- name: myservice
+  image: alpine:latest
+  binds:
+  - volA:/mnt/volA:ro
+  - volB:/mnt/volB
+```
+
+### `files`
+
+The files section can be used to add files inline in the config, or from an external file.
+
+```yml
+files:
+  - path: dir
+    directory: true
+    mode: "0777"
+  - path: dir/name1
+    source: "/some/path/on/local/filesystem"
+    mode: "0666"
+  - path: dir/name2
+    source: "/some/path/that/it/is/ok/to/omit"
+    optional: true
+    mode: "0666"
+  - path: dir/name3
+    contents: "orange"
+    mode: "0644"
+    uid: 100
+    gid: 100
+```
+
+Specifying the `mode` is optional, and will default to `0600`. Leading directories will be
+created if not specified. You can use `~/path` in `source` to specify a path in the build
+user's home directory.
+
+In addition there is a `metadata` option that will generate the file. Currently the only value
+supported here is `"yaml"` which will output the yaml used to generate the image into the specified
+file:
+
+```yml
+  - path: etc/linuxkit.yml
+    metadata: yaml
+```
+
+Note that if you use templates in the yaml, the final resolved version will be included in the image,
+and not the original input template.
+
+Because a `tmpfs` is mounted onto `/var`, `/run`, and `/tmp` by default, the `tmpfs` mounts will shadow anything specified in `files` section for those directories.
+
+## Image specification
+
+Entries in the `onboot`, `onshutdown`, `volumes` and `services` sections specify an OCI image and
+options. Default values may be specified using the `org.mobyproject.config` image label.
+For more details see the [OCI specification](https://github.com/opencontainers/runtime-spec/blob/master/spec.md).
+
+If the `org.mobylinux.config` label is set in the image, that specifies default values for these fields if they
+are not set in the yaml file. While most fields are _replaced_ if they are specified in the yaml file,
+some support _add_ via the format `<field>.add`; see below.
+You can override the label entirely by setting the value, or setting it to be empty to remove
+the specification for that value in the label.
+
+If you need an OCI option that is not specified here please open an issue or pull request as the list is not yet
+complete.
+
+By default the containers will be run in the host `net`, `ipc` and `uts` namespaces, as that is the usual requirement;
+in many ways they behave like pods in Kubernetes. Mount points must already exist, as must a file or directory being
+bind mounted into a container.
+
+- `name` a unique name for the program being executed, used as the `containerd` id.
+- `image` the Docker image to use for the root filesystem. The default command, path and environment are
+  extracted from this so they need not be filled in.
+- `capabilities` the Linux capabilities required, for example `CAP_SYS_ADMIN`. If there is a single
+  capability `all` then all capabilities are added.
+- `capabilities.add` the Linux capabilities required, but these are added to the defaults, rather than overriding them.
+- `ambient` the Linux ambient capabilities (capabilities passed to non root users) that are required.
+- `mounts` is the full form for specifying a mount, which requires `type`, `source`, `destination`
+  and a list of `options`. If any fields are omitted, sensible defaults are used if possible, for example
+  if the `type` is `dev` it is assumed you want to mount at `/dev`. The default mounts and their options
+  can be replaced by specifying a mount with new options here at the same mount point.
+- `binds` is a simpler interface to specify bind mounts, accepting a string like `/src:/dest:opt1,opt2`
+  similar to the `-v` option for bind mounts in Docker.
+- `binds.add` is a simpler interface to specify bind mounts, but these are added to the defaults, rather than overriding them.
+- `tmpfs` is a simpler interface to mount a `tmpfs`, like `--tmpfs` in Docker, taking `/dest:opt1,opt2`.
+- `command` will override the command and entrypoint in the image with a new list of commands.
+- `env` will override the environment in the image with a new environment list. Specify variables as `VAR=value`.
+- `cwd` will set the working directory, defaults to `/`.
+- `net` sets the network namespace, either to a path, or if `none` or `new` is specified it will use a new namespace.
+- `ipc` sets the ipc namespace, either to a path, or if `new` is specified it will use a new namespace.
+- `uts` sets the uts namespace, either to a path, or if `new` is specified it will use a new namespace.
+- `pid` sets the pid namespace, either to a path, or if `host` is specified it will use the host namespace.
+- `readonly` sets the root filesystem to read only, and changes the other default filesystems to read only.
+- `maskedPaths` sets paths which should be hidden.
+- `readonlyPaths` sets paths to read only.
+- `uid` sets the user id of the process.
+- `gid` sets the group id of the process.
+- `additionalGids` sets a list of additional groups for the process.
+- `noNewPrivileges` is `true` means no additional capabilities can be acquired and `suid` binaries do not work.
+- `hostname` sets the hostname inside the image.
+- `oomScoreAdj` changes the OOM score.
+- `rootfsPropagation` sets the rootfs propagation, eg `shared`, `slave` or (default) `private`.
+- `cgroupsPath` sets the path for cgroups.
+- `resources` sets cgroup resource limits as per the OCI spec.
+- `sysctl` sets a map of `sysctl` key value pairs that are set inside the container namespace.
+- `rmlimits` sets a list of `rlimit` values in the form `name,soft,hard`, eg `nofile,100,200`. You can use `unlimited` as a value too.
+- `annotations` sets a map of key value pairs as OCI metadata.
+
+There are experimental `userns`, `uidMappings` and `gidMappings` options for user namespaces but these are not yet supported, and may have
+permissions issues in use.
+
+In addition to the parts of the specification above used to generate the OCI spec, there is a `runtime` section in the image specification
+which specifies some actions to take place when the container is being started.
+- `cgroups` takes a list of cgroups that will be created before the container is run.
+- `mounts` takes a list of mount specifications (`source`, `destination`, `type`, `options`) and mounts them in the root namespace before the container is created. It will
+  try to make any missing destination directories.
+- `mkdir` takes a list of directories to create at runtime, in the root mount namespace. These are created before the container is started, so they can be used to create
+  directories for bind mounts, for example in `/tmp` or `/run` which would otherwise be empty.
+- `interface` defines a list of actions to perform on a network interface:
+  - `name` specifies the name of an interface. An existing interface with this name will be moved into the container's network namespace.
+  - `add` specifies a type of interface to be created in the containers namespace, with the specified name.
+  - `createInRoot` is a boolean which specifes that the interface being `add`ed should be created in the root namespace first, then moved. This is needed for `wireguard` interfaces.
+  - `peer` specifies the name of the other end when creating a `veth` interface. This end will remain in the root namespace, where it can be attached to a bridge. Specifying this implies `add: veth`.
+- `bindNS` specifies a namespace type and a path where the namespace from the container being created will be bound. This allows a namespace to be set up in an `onboot` container, and then
+  using `net: path` for a `service` container to use that network namespace later.
+- `namespace` overrides the LinuxKit default containerd namespace to put the container in; only applicable to services.
+
+An example of using the `runtime` config to configure a network namespace with `wireguard` and then run `nginx` in that namespace is shown below:
+
+```yml
+onboot:
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:<hash>
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: wg
+    image: linuxkit/ip:<hash>
+    net: new
+    binds:
+      - /etc/wireguard:/etc/wireguard
+    command: ["sh", "-c", "ip link set dev wg0 up; ip address add dev wg0 192.168.2.1 peer 192.168.2.2; wg setconf wg0 /etc/wireguard/wg0.conf; wg show wg0"]
+    runtime:
+      interfaces:
+        - name: wg0
+          add: wireguard
+          createInRoot: true
+      bindNS:
+        net: /run/netns/wg
+services:
+  - name: nginx
+    image: nginx:alpine
+    net: /run/netns/wg
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+```
+
+## `devices`
+
+To access the console, it's necessary to explicitly add a "device" definition, for example:
+
+```
+devices:
+- path: "/dev/console"
+  type: c
+  major: 5
+  minor: 1
+  mode: 0666
+```
+
+See the [getty package](../pkg/getty/build.yml) for a more complete example
+and see [runc](https://github.com/opencontainers/runc/commit/60e21ec26e15945259d4b1e790e8fd119ee86467) for context.
+
+To grant access to all block devices use:
+
+```
+devices:
+- path: all
+  type: b
+```
+
+See the [format package](../pkg/format/build.yml) for an example.
+
+### Mount Options
+When mounting filesystem paths into a container - whether as part of `onboot` or `services` - there are several options of which you need to be aware. Using them properly is necessary for your containers to function properly.
+
+For most containers - e.g. nginx or even docker - these options are not needed. Simply doing the following will work fine:
+
+```yml
+binds:
+ - /var:/some/var/path
+```
+
+Please note that `binds` doesn't **add** the mount points, but **replaces** them.
+You can examine the `Dockerfile` of the component (in particular, `binds` value of
+`org.mobyproject.config` label) to get the list of the existing binds.
+
+However, in some circumstances you will need additional options. These options are used primarily if you intend to make changes to mount points _from within your container_ that should be visible from outside the container, e.g., if you intend to mount an external disk from inside the container but have it be visible outside.
+
+In order for new mounts from within a container to be propagated, you must set the following on the container:
+
+1. `rootfsPropagation: shared`
+2. The mount point into the container below which new mounts are to occur must be `rshared,rbind`. In practice, this is `/var` (or some subdir of `/var`), since that is the only true read-write area of the filesystem where you will mount things.
+
+Thus, if you have a regular container that is only reading and writing, go ahead and do:
+
+```yml
+binds:
+ - /var:/some/var/path
+```
+
+On the other hand, if you have a container that will make new mounts that you wish to be visible outside the container, do:
+
+```yml
+binds:
+ - /var:/var:rshared,rbind
+rootfsPropagation: shared
+```
+
+## Templates
+
+The `yaml` file supports templates for the names of images. Anyplace an image is used in a file and begins
+with the character `@`, it indicates that it is not an actual name, but a template. The first word after
+the `@` indicates the type of template, and the rest of the line is the argument to the template. The
+templates currently supported are:
+
+* `@pkg:` - the argument is the path to a linuxkit package. For example, `@pkg:./pkg/init`.
+
+For `pkg`, linuxkit will resolve the path to the package, and then run the equivalent of `linuxkit pkg show-tag <dir>`.
+For example:
+
+```yaml
+init:
+  - "@pkg:../pkg/init"
+```
+
+Will cause linuxkit to resolve `../pkg/init` to a package, and then run `linuxkit pkg show-tag ../pkg/init`.
+
+The paths are relative to the directory of the yaml file.
+You can specify absolute paths, although it is not recommended, as that can make the yaml file less portable.
+
+The `@pkg:` templating is supported **only** when the yaml file is being read from a local filesystem. It does not
+support when using via stdin, e.g. `cat linuxkit.yml | linuxkit build -`, or URLs, e.g. `linuxkit build https://example.com/foo.yml`.
+
+The `@pkg:` template currently supports only default `linuxkit pkg` options, i.e. `build.yml` and `tag` options. There
+are no command-line options to override them.
+
+**Note:** The character `@` is reserved in yaml. To use it in the beginning of a string, you must put the entire string in
+quotes.
+
+If you use the template, the actual derived value, and not the initial template, is what will be stored in the final
+image when adding it via:
+
+```yaml
+files:
+  - path: etc/linuxkit.yml
+    metadata: yaml
+```

examples/addbinds.yml

@@ -0,0 +1,26 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    binds.add:
+      # this will keep all of the existing ones as well
+      - /var/tmp:/var/tmp
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+files:
+  - path: etc/getty.shadow
+    # sample sets password for root to "abcdefgh" (without quotes)
+    contents: 'root:$6$6tPd2uhHrecCEKug$8mKfcgfwguP7f.BLdZsT1Wz7WIIJOBY1oUFHzIv9/O71M2J0EPdtFqFGTxB1UK5ejqQxRFQ.ZSG9YXR0SNsc11:17322:0:::::'

examples/aws.yml

@@ -1,37 +0,0 @@
-kernel:
-  image: linuxkit/kernel:4.14.40
-  cmdline: "console=ttyS0"
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
-onboot:
-  - name: sysctl
-    image: linuxkit/sysctl:v0.4
-  - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
-    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
-  - name: metadata
-    image: linuxkit/metadata:v0.4
-services:
-  - name: rngd
-    image: linuxkit/rngd:v0.4
-  - name: sshd
-    image: linuxkit/sshd:v0.4
-    binds:
-     - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
-  - name: nginx
-    image: nginx:1.13.8-alpine
-    capabilities:
-     - CAP_NET_BIND_SERVICE
-     - CAP_CHOWN
-     - CAP_SETUID
-     - CAP_SETGID
-     - CAP_DAC_OVERRIDE
-    binds:
-     - /etc/resolv.conf:/etc/resolv.conf
-trust:
-  org:
-    - linuxkit
-    - library

examples/azure.yml

@@ -1,26 +0,0 @@
-kernel:
-  image: linuxkit/kernel:4.14.40
-  cmdline: "console=ttyS0"
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
-onboot:
-  - name: sysctl
-    image: linuxkit/sysctl:v0.4
-services:
-  - name: rngd
-    image: linuxkit/rngd:v0.4
-  - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
-  - name: sshd
-    image: linuxkit/sshd:v0.4
-files:
-  - path: root/.ssh/authorized_keys
-    source: ~/.ssh/id_rsa.pub
-    mode: "0600"
-    optional: true
-trust:
-  org:
-    - linuxkit

examples/cadvisor.yml

@@ -1,37 +1,37 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
   - name: sysfs
-    image: linuxkit/sysfs:v0.4
+    image: linuxkit/sysfs:ec174e06ca756f492e7a3fd6200d5c1672b97511
   - name: format
-    image: linuxkit/format:v0.4
+    image: linuxkit/format:e040f4f045f03138a1ee8a22bb6feae7fd5596a6
   - name: mount
-    image: linuxkit/mount:v0.4
+    image: linuxkit/mount:19ff89c251a4156bda8ed11c95faad2f40eb770e
     command: ["/usr/bin/mountie", "/var/lib/docker"]
 
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
       - INSECURE=true
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
   - name: ntpd
-    image: linuxkit/openntpd:v0.4
+    image: linuxkit/openntpd:c90c6dd90f5dfb0ca71a73aac2dad69c8d956af3
 
   - name: docker
-    image: docker:17.10.0-ce-dind
+    image: docker:20.10.6-dind
     capabilities:
       - all
     net: host
@@ -46,14 +46,10 @@ services:
       - /etc/docker/daemon.json:/etc/docker/daemon.json
     command: ["/usr/local/bin/docker-init", "/usr/local/bin/dockerd"]
   - name: cadvisor
-    image: linuxkit/cadvisor:v0.4
+    image: linuxkit/cadvisor:c57efffad1139b2c5df1c3f66c1e3d586ce9e07d
 files:
   - path: var/lib/docker
     directory: true
   - path: etc/docker/daemon.json
     contents: '{"debug": true, "hosts": ["unix:///var/run/docker.sock"]}'
     mode: "0644"
-trust:
-  org:
-    - linuxkit
-    - library

examples/containerd-debug-runtime-config.toml

@@ -0,0 +1,4 @@
+cliopts="--log-level trace"
+stderr="/var/log/containerd.err.log"
+stdout="/var/log/containerd.out.log"
+

examples/containerd-debug.yml

@@ -0,0 +1,42 @@
+# example with volumes, both blank and populated
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+onshutdown:
+  - name: shutdown
+    image: busybox:latest
+    command: ["/bin/echo", "so long and thanks for all the fish"]
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:cdb919e4aee49fed0bf6075f0a104037cba83c39
+  - name: nginx
+    image: nginx:1.19.5-alpine
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+    binds:
+     - /etc/resolv.conf:/etc/resolv.conf
+files:
+  - path: etc/linuxkit-config
+    metadata: yaml
+  - path: /etc/containerd/runtime-config.toml
+    source: "containerd-debug-runtime-config.toml"  # must include the file runtime-config.toml in this directory
+    mode: "0644"

examples/dm-crypt-loop.yml

@@ -0,0 +1,46 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: format
+    image: linuxkit/format:e040f4f045f03138a1ee8a22bb6feae7fd5596a6
+    command: ["/usr/bin/format", "/dev/sda"]
+  - name: mount
+    image: linuxkit/mount:19ff89c251a4156bda8ed11c95faad2f40eb770e
+    command: ["/usr/bin/mountie", "/dev/sda1", "/var/external"]
+  - name: loop
+    image: linuxkit/losetup:65e3ad6336a321749394f58c3f28003cfce1e28c
+    command: ["/usr/bin/loopy", "--create", "/var/external/storage_file"]
+  - name: dm-crypt
+    image: linuxkit/dm-crypt:d49723bc9d10c5ada9e03b0670f4e57416d5d084
+    command: ["/usr/bin/crypto", "crypt_loop_dev", "/dev/loop0"]
+  - name: mount
+    image: linuxkit/mount:19ff89c251a4156bda8ed11c95faad2f40eb770e
+    command: ["/usr/bin/mountie", "/dev/mapper/crypt_loop_dev", "/var/secure_storage"]
+  - name: bbox
+    image: busybox
+    command: ["sh", "-c", "echo 'secret things' >/var/secure_storage/secrets"]
+    binds:
+      - /var:/var
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+files:
+  - path: etc/dm-crypt/key
+    # the below key is just to keep the example self-contained
+    # !!! provide a proper key for production use here !!!
+    contents: "abcdefghijklmnopqrstuvwxyz123456"

examples/dm-crypt.yml

@@ -0,0 +1,40 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: format
+    image: linuxkit/format:e040f4f045f03138a1ee8a22bb6feae7fd5596a6
+    command: ["/usr/bin/format", "/dev/sda"]
+  - name: dm-crypt
+    image: linuxkit/dm-crypt:d49723bc9d10c5ada9e03b0670f4e57416d5d084
+    command: ["/usr/bin/crypto", "crypt_dev", "/dev/sda1"]
+  - name: mount
+    image: linuxkit/mount:19ff89c251a4156bda8ed11c95faad2f40eb770e
+    command: ["/usr/bin/mountie", "/dev/mapper/crypt_dev", "/var/secure_storage"]
+  - name: bbox
+    image: busybox
+    command: ["sh", "-c", "echo 'secret things' >/var/secure_storage/secrets"]
+    binds:
+      - /var:/var
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+files:
+  - path: etc/dm-crypt/key
+    # the below key is just to keep the example self-contained
+    # !!! provide a proper key for production use here !!!
+    contents: "abcdefghijklmnopqrstuvwxyz123456"

examples/docker-for-mac.md

@@ -10,13 +10,13 @@ moment is to install a recent version of Docker for Mac.
 To build it with the latest Docker CE:
 
 ```
-$ linuxkit build docker-for-mac.yml
+$ linuxkit build -format iso-efi docker-for-mac.yml
 ```
 
 To run the VM with a 4G disk:
 
 ```
-linuxkit run hyperkit -networking=vpnkit -vsock-ports=2376 -disk size=4096M -data-file ./metadata.json docker-for-mac
+linuxkit run hyperkit --networking=vpnkit --vsock-ports=2376 --disk size=4096M --data-file ./metadata.json --iso --uefi docker-for-mac-efi
 ```
 
 Where the file `./metadata.json` should contain the desired docker daemon
@@ -35,10 +35,10 @@ configuration, for example:
 ```
 
 In another terminal you should now be able to access docker via the
-socket `guest.00000947` in the state directory
-(`docker-for-mac-state/` by default):
+socket `guest.00000948` in the state directory
+(`docker-for-mac-efi-state/` by default):
 
 ```
-$ docker -H unix://docker-for-mac-state/guest.00000948 ps
+$ docker -H unix://docker-for-mac-efi-state/guest.00000948 ps
 CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
 ```

examples/docker-for-mac.yml

@@ -1,36 +1,36 @@
 # This is an example for building the open source components of Docker for Mac
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=ttyS0 page_poison=1"
 init:
-  - linuxkit/vpnkit-expose-port:v0.4 # install vpnkit-expose-port and vpnkit-iptables-wrapper on host
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/vpnkit-expose-port:77e45e4681c78d59f1d8a48818260948d55f9d05 # install vpnkit-expose-port and vpnkit-iptables-wrapper on host
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   # support metadata for optional config in /run/config
   - name: metadata
-    image: linuxkit/metadata:v0.4
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: sysfs
-    image: linuxkit/sysfs:v0.4
+    image: linuxkit/sysfs:ec174e06ca756f492e7a3fd6200d5c1672b97511
   - name: binfmt
-    image: linuxkit/binfmt:v0.4
+    image: linuxkit/binfmt:68604c81876812ca1c9e2d9f098c28f463713e61
   # Format and mount the disk image in /var/lib/docker
   - name: format
-    image: linuxkit/format:v0.4
+    image: linuxkit/format:e040f4f045f03138a1ee8a22bb6feae7fd5596a6
   - name: mount
-    image: linuxkit/mount:v0.4
+    image: linuxkit/mount:19ff89c251a4156bda8ed11c95faad2f40eb770e
     command: ["/usr/bin/mountie", "/var/lib"]
   # make a swap file on the mounted disk
   - name: swap
-    image: linuxkit/swap:v0.4
+    image: linuxkit/swap:c57f3319ce770515357f0058035e40519c22b752
     command: ["/swap.sh", "--path", "/var/lib/swap", "--size", "1024M"]
   # mount-vpnkit mounts the 9p share used by vpnkit to coordinate port forwarding
   - name: mount-vpnkit
-    image: alpine:3.7
+    image: alpine:3.13
     binds:
         - /var/:/host_var:rbind,rshared
     capabilities:
@@ -39,51 +39,51 @@ onboot:
     command: ["sh", "-c", "mkdir -p /host_var/vpnkit/port && mount -v -t 9p -o trans=virtio,dfltuid=1001,dfltgid=50,version=9p2000 port /host_var/vpnkit"]
   # move logs to the mounted disk (this is a temporary fix until we can limit the log sizes)
   - name: move-logs
-    image: alpine:3.7
+    image: alpine:3.13
     binds:
         - /var:/host_var
     command: ["sh", "-c", "mv -v /host_var/log /host_var/lib && ln -vs /var/lib/log /host_var/log"]
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 services:
   # Enable acpi to shutdown on power events
   - name: acpid
-    image: linuxkit/acpid:v0.4
+    image: linuxkit/acpid:3b1560c81d3884e049ebbd9d9bf94ccb394e6cd3
   # Enable getty for easier debugging
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
         - INSECURE=true
   # Run ntpd to keep time synchronised in the VM
   - name: ntpd
-    image: linuxkit/openntpd:v0.4
+    image: linuxkit/openntpd:c90c6dd90f5dfb0ca71a73aac2dad69c8d956af3
   # VSOCK to unix domain socket forwarding. Forwards guest /var/run/docker.sock
   # to a socket on the host.
   - name: vsudd
-    image: linuxkit/vsudd:v0.4
+    image: linuxkit/vsudd:b4d80d243733f80906cdbcf77f367a7b5744dc09
     binds:
         - /var/run:/var/run
     command: ["/vsudd", "-inport", "2376:unix:/var/run/docker.sock"]
   # vpnkit-forwarder forwards network traffic to/from the host via VSOCK port 62373. 
   # It needs access to the vpnkit 9P coordination share 
   - name: vpnkit-forwarder
-    image: linuxkit/vpnkit-forwarder:v0.4
+    image: linuxkit/vpnkit-forwarder:a89ec807d7d675dccd53773c07382bc707db3396
     binds:
         - /var/vpnkit:/port
     net: host
     command: ["/vpnkit-forwarder", "-vsockPort", "62373"]
   # Monitor for image deletes and invoke a TRIM on the container filesystem
   - name: trim-after-delete
-    image: linuxkit/trim-after-delete:v0.4
+    image: linuxkit/trim-after-delete:6ba98bfb111a808b7a1ca890aca9fc2b3709fca2
   # When the host resumes from sleep, force a clock resync
   - name: host-timesync-daemon
-    image: linuxkit/host-timesync-daemon:v0.4
+    image: linuxkit/host-timesync-daemon:0d351aee24b5cf853927647e4f5e6998014959db
   # Run dockerd with the vpnkit userland proxy from the vpnkit-forwarder container.
   # Bind mounts /var/run to allow vsudd to connect to docker.sock, /var/vpnkit
   # for vpnkit coordination and /run/config/docker for the configuration file.
   - name: docker-dfm
-    image: docker:17.07.0-ce-dind
+    image: docker:20.10.6-dind
     capabilities:
      - all
     net: host
@@ -106,8 +106,3 @@ services:
             "--storage-driver", "overlay2" ]
     runtime:
       mkdir: ["/var/lib/docker"]
-
-trust:
-    org:
-        - linuxkit
-        - library

examples/docker.yml

@@ -1,34 +1,34 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: sysfs
-    image: linuxkit/sysfs:v0.4
+    image: linuxkit/sysfs:ec174e06ca756f492e7a3fd6200d5c1672b97511
   - name: format
-    image: linuxkit/format:v0.4
+    image: linuxkit/format:e040f4f045f03138a1ee8a22bb6feae7fd5596a6
   - name: mount
-    image: linuxkit/mount:v0.4
+    image: linuxkit/mount:19ff89c251a4156bda8ed11c95faad2f40eb770e
     command: ["/usr/bin/mountie", "/var/lib/docker"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
   - name: ntpd
-    image: linuxkit/openntpd:v0.4
+    image: linuxkit/openntpd:c90c6dd90f5dfb0ca71a73aac2dad69c8d956af3
   - name: docker
-    image: docker:17.09.0-ce-dind
+    image: docker:20.10.6-dind
     capabilities:
      - all
     net: host
@@ -46,7 +46,3 @@ files:
     directory: true
   - path: etc/docker/daemon.json
     contents: '{"debug": true}'
-trust:
-  org:
-    - linuxkit
-    - library

examples/gcp.yml

@@ -1,41 +0,0 @@
-kernel:
-  image: linuxkit/kernel:4.14.40
-  cmdline: "console=ttyS0"
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
-onboot:
-  - name: sysctl
-    image: linuxkit/sysctl:v0.4
-  - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
-    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
-  - name: metadata
-    image: linuxkit/metadata:v0.4
-services:
-  - name: getty
-    image: linuxkit/getty:v0.4
-    env:
-     - INSECURE=true
-  - name: rngd
-    image: linuxkit/rngd:v0.4
-  - name: sshd
-    image: linuxkit/sshd:v0.4
-    binds:
-     - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
-  - name: nginx
-    image: nginx:1.13.8-alpine
-    capabilities:
-     - CAP_NET_BIND_SERVICE
-     - CAP_CHOWN
-     - CAP_SETUID
-     - CAP_SETGID
-     - CAP_DAC_OVERRIDE
-    binds:
-     - /etc/resolv.conf:/etc/resolv.conf
-trust:
-  org:
-    - linuxkit
-    - library

examples/getty.yml

@@ -1,29 +1,26 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     # to make insecure with passwordless root login, uncomment following lines
     #env:
     # - INSECURE=true
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
 files:
   - path: etc/getty.shadow
     # sample sets password for root to "abcdefgh" (without quotes)
     contents: 'root:$6$6tPd2uhHrecCEKug$8mKfcgfwguP7f.BLdZsT1Wz7WIIJOBY1oUFHzIv9/O71M2J0EPdtFqFGTxB1UK5ejqQxRFQ.ZSG9YXR0SNsc11:17322:0:::::'
-trust:
-  org:
-    - linuxkit

examples/hostmount-writeable-overlay.yml

@@ -1,16 +1,16 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 onshutdown:
   - name: shutdown
@@ -18,7 +18,7 @@ onshutdown:
     command: ["/bin/echo", "so long and thanks for all the fish"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
     runtime:
@@ -30,7 +30,7 @@ services:
           destination: writeable-host-etc
           options: ["rw", "lowerdir=/etc", "upperdir=/run/hostetc/upper", "workdir=/run/hostetc/work"]
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
   - name: nginx
     image: nginx:1.13.8-alpine
     capabilities:
@@ -41,7 +41,3 @@ services:
      - CAP_DAC_OVERRIDE
     binds:
      - /etc/resolv.conf:/etc/resolv.conf
-trust:
-  org:
-    - linuxkit
-    - library

examples/influxdb-os.yml

@@ -1,48 +1,44 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
   - name: influxdb
-    image: influxdb:1.4
+    image: influxdb:1.7
     net: host
     capabilities:
       - CAP_NET_BIND_SERVICE
       - CAP_DAC_OVERRIDE
   - name: kapacitor
-    image: kapacitor:1.4
+    image: kapacitor:1.5
     net: host
     capabilities:
       - all
     env:
       - KAPACITOR_INFLUXDB_0_URLS_0=http://influxdb:8086
   - name: telegraf
-    image: telegraf:1.4
+    image: telegraf:1.9
     net: host
     capabilities:
       - all
   - name: chronograf
-    image: chronograf:1.4
+    image: chronograf:1.7
     net: host
     capabilities:
       - CAP_NET_BIND_SERVICE
       - CAP_DAC_OVERRIDE
     env:
-      - INFLUXDB_URL=http://localhost:8086
-      - KAPACITOR_URL=http://localhost:9092
-trust:
-  org:
-    - linuxkit
-    - library
+      - INFLUXDB_URL=http://127.0.0.1:8086
+      - KAPACITOR_URL=http://127.0.0.1:9092

examples/logging.yml

@@ -0,0 +1,30 @@
+# Simple example of using an external logging service
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+  - linuxkit/memlogd:cb79fd19e6485cfc61b85c607ca172cd860554c5
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+services:
+# Inside the getty type `/proc/1/root/usr/bin/logread -F` to follow the log
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+# A service which generates log messages for testing
+  - name: write-to-the-logs
+    image: alpine:3.13
+    command: ["/bin/sh", "-c", "while /bin/true; do echo hello $(date); sleep 1; done" ]
+  - name: write-and-rotate-logs
+    image: linuxkit/logwrite:c1c66d246080a40658903916d650206f2dcd707a
+  - name: kmsg
+    image: linuxkit/kmsg:423844f262467e1199480dc93d69e38610c78133

examples/minimal.yml

@@ -1,19 +1,16 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
 onboot:
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
-trust:
-  org:
-    - linuxkit

examples/node_exporter.yml

@@ -1,21 +1,18 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
   - name: node_exporter
-    image: linuxkit/node_exporter:v0.4
-trust:
-  org:
-    - linuxkit
+    image: linuxkit/node_exporter:9bcd8479b7ba2844773ef4f01a60c901c4800982

examples/openstack.yml

@@ -1,26 +1,26 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=ttyS0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
   - name: metadata
-    image: linuxkit/metadata:v0.4
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
     command: ["/usr/bin/metadata", "openstack"]
 services:
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
   - name: sshd
-    image: linuxkit/sshd:v0.4
-    binds:
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
      - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
   - name: nginx
     image: nginx:1.13.8-alpine
@@ -32,7 +32,3 @@ services:
      - CAP_DAC_OVERRIDE
     binds:
      - /etc/resolv.conf:/etc/resolv.conf
-trust:
-  org:
-    - linuxkit
-    - library

examples/packet.arm64.yml

@@ -1,14 +0,0 @@
-# This YAML snippet is to be used in conjunction with packet.yml to
-# build a arm64 image for packet.net. It adds a modprobe of the NIC
-# driver and overrides the kernel section to disable prepending the
-# Intel CPU microcode to the initrd. If writing a YAML specifically
-# for arm64 then the 'ucode' line in the kernel section can be left
-# out.
-kernel:
-  image: linuxkit/kernel:4.14.40
-  cmdline: "console=ttyAMA0"
-  ucode: ""
-onboot:
-  - name: modprobe
-    image: linuxkit/modprobe:v0.4
-    command: ["modprobe", "nicvf"]

examples/packet.yml

@@ -1,39 +0,0 @@
-kernel:
-  image: linuxkit/kernel:4.14.40
-  cmdline: console=ttyS1
-  ucode: intel-ucode.cpio
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
-  - linuxkit/firmware:v0.4
-onboot:
-  - name: rngd1
-    image: linuxkit/rngd:v0.4
-    command: ["/sbin/rngd", "-1"]
-  - name: sysctl
-    image: linuxkit/sysctl:v0.4
-  - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
-    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
-  - name: metadata
-    image: linuxkit/metadata:v0.4
-    command: ["/usr/bin/metadata", "packet"]
-services:
-  - name: rngd
-    image: linuxkit/rngd:v0.4
-  - name: getty
-    image: linuxkit/getty:v0.4
-    env:
-     - INSECURE=true
-  - name: sshd
-    image: linuxkit/sshd:v0.4
-files:
-  - path: root/.ssh/authorized_keys
-    source: ~/.ssh/id_rsa.pub
-    mode: "0600"
-    optional: true
-trust:
-  org:
-    - linuxkit

examples/platform-aws.yml

@@ -0,0 +1,36 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=ttyS0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: metadata
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
+services:
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: dhcpcd2
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf"]
+  - name: sshd
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+     - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
+  - name: nginx
+    image: nginx:1.13.8-alpine
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+    binds:
+     - /etc/resolv.conf:/etc/resolv.conf

examples/platform-azure.yml

@@ -0,0 +1,25 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=ttyS0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+services:
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+  - name: sshd
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+      - /root/.ssh:/root/.ssh
+files:
+  - path: root/.ssh/authorized_keys
+    source: ~/.ssh/id_rsa.pub
+    mode: "0600"
+    optional: true

examples/platform-equinixmetal.arm64.yml

@@ -0,0 +1,14 @@
+# This YAML snippet is to be used in conjunction with equinixmetal.yml to
+# build a arm64 image for Equinix Metal. It adds a modprobe of the NIC
+# driver and overrides the kernel section to disable prepending the
+# Intel CPU microcode to the initrd. If writing a YAML specifically
+# for arm64 then the 'ucode' line in the kernel section can be left
+# out.
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=ttyAMA0"
+  ucode: ""
+onboot:
+  - name: modprobe
+    image: linuxkit/modprobe:ab5ac4d5e7e7a5f2d103764850f7846b69230676
+    command: ["modprobe", "nicvf"]

examples/platform-equinixmetal.yml

@@ -0,0 +1,38 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: console=ttyS1
+  ucode: intel-ucode.cpio
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+  - linuxkit/firmware:8def159583422181ddee3704f7024ecb9c02d348
+onboot:
+  - name: rngd1
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+    command: ["/sbin/rngd", "-1"]
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: metadata
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
+    command: ["/usr/bin/metadata", "equinixmetal"]
+services:
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: sshd
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+      - /root/.ssh:/root/.ssh
+files:
+  - path: root/.ssh/authorized_keys
+    source: ~/.ssh/id_rsa.pub
+    mode: "0600"
+    optional: true

examples/platform-gcp.yml

@@ -0,0 +1,37 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=ttyS0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: metadata
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: sshd
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+     - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
+  - name: nginx
+    image: nginx:1.13.8-alpine
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+    binds:
+     - /etc/resolv.conf:/etc/resolv.conf

examples/platform-hetzner.yml

@@ -0,0 +1,38 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: console=ttyS1
+  ucode: intel-ucode.cpio
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+  - linuxkit/firmware:8def159583422181ddee3704f7024ecb9c02d348
+onboot:
+  - name: rngd1
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+    command: ["/sbin/rngd", "-1"]
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: metadata
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
+    command: ["/usr/bin/metadata", "hetzner"]
+services:
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: sshd
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+      - /root/.ssh:/root/.ssh
+files:
+  - path: root/.ssh/authorized_keys
+    source: ~/.ssh/id_rsa.pub
+    mode: "0600"
+    optional: true

examples/platform-rt-for-vmware.yml

@@ -0,0 +1,32 @@
+kernel:
+  image: linuxkit/kernel:6.6.13-rt
+  cmdline: "console=tty0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+  - name: open-vm-tools
+    image: linuxkit/open-vm-tools:728ddf726474178eea97604c0baeabd52edab7e9
+  - name: nginx
+    image: nginx:1.13.8-alpine
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+    binds:
+     - /etc/resolv.conf:/etc/resolv.conf

examples/platform-scaleway.yml

@@ -0,0 +1,26 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0 root=/dev/vda"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: rngd1
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+    command: ["/sbin/rngd", "-1"]
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: metadata
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd

examples/platform-vmware.yml

@@ -0,0 +1,30 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+  - name: nginx
+    image: nginx:1.13.8-alpine
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+    binds:
+     - /etc/resolv.conf:/etc/resolv.conf

examples/platform-vultr.yml

@@ -0,0 +1,38 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=ttyS0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+  - name: metadata
+    image: linuxkit/metadata:b082f1bf97a9034d1e4c0e36a5d2923f4e58f540
+    command: ["/usr/bin/metadata", "vultr"]
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
+  - name: sshd
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+     - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
+  - name: nginx
+    image: nginx:1.13.8-alpine
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+    binds:
+     - /etc/resolv.conf:/etc/resolv.conf

examples/redis-os.yml

@@ -1,19 +1,19 @@
 # Minimal YAML to run a redis server (used at DockerCon'17)
 # connect: nc localhost 6379
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
 onboot:
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
   # Currently redis:4.0.6-alpine has trust issue with multi-arch
@@ -27,7 +27,3 @@ services:
      - CAP_SETGID
      - CAP_DAC_OVERRIDE
     net: host
-trust:
-  org:
-    - linuxkit
-    - library

examples/rt-for-vmware.yml

@@ -1,36 +0,0 @@
-kernel:
-  image: linuxkit/kernel:4.14.34-rt
-  cmdline: "console=tty0"
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
-onboot:
-  - name: sysctl
-    image: linuxkit/sysctl:v0.4
-services:
-  - name: getty
-    image: linuxkit/getty:v0.4
-    env:
-     - INSECURE=true
-  - name: rngd
-    image: linuxkit/rngd:v0.4
-  - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
-  - name: open-vm-tools
-    image: linuxkit/open-vm-tools:v0.4
-  - name: nginx
-    image: nginx:1.13.8-alpine
-    capabilities:
-     - CAP_NET_BIND_SERVICE
-     - CAP_CHOWN
-     - CAP_SETUID
-     - CAP_SETGID
-     - CAP_DAC_OVERRIDE
-    binds:
-     - /etc/resolv.conf:/etc/resolv.conf
-trust:
-  org:
-    - linuxkit
-    - library

examples/sshd.yml

@@ -1,33 +1,32 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: rngd1
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
     command: ["/sbin/rngd", "-1"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
   - name: sshd
-    image: linuxkit/sshd:v0.4
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+      - /root/.ssh:/root/.ssh
 files:
   - path: root/.ssh/authorized_keys
     source: ~/.ssh/id_rsa.pub
     mode: "0600"
     optional: true
-trust:
-  org:
-    - linuxkit

examples/static-ip.yml

@@ -0,0 +1,29 @@
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+onboot:
+  - name: ip
+    image: linuxkit/ip:bb250017b05de5e16ac436b1eb19a39c87b5a252
+    binds:
+     - /etc/ip:/etc/ip
+    command: ["ip", "-b", "/etc/ip/eth0.conf"]
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+files:     
+  - path: etc/ip/eth0.conf
+    contents: |
+      address add 10.10.1.225/24 dev eth0
+      link set eth0 up
+      route add default via 10.10.1.100 dev eth0
+  - path: etc/resolv.conf
+    contents: |
+#      domain test.local
+      nameserver 10.10.1.101
+      nameserver 10.10.1.100     

examples/swap.yml

@@ -1,35 +1,31 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
   - name: format
-    image: linuxkit/format:v0.4
+    image: linuxkit/format:e040f4f045f03138a1ee8a22bb6feae7fd5596a6
   - name: mount
-    image: linuxkit/mount:v0.4
+    image: linuxkit/mount:19ff89c251a4156bda8ed11c95faad2f40eb770e
     command: ["/usr/bin/mountie", "/var/external"]
   - name: swap
-    image: linuxkit/swap:v0.4
+    image: linuxkit/swap:c57f3319ce770515357f0058035e40519c22b752
     # to use unencrypted swap, use:
     # command: ["/swap.sh", "--path", "/var/external/swap", "--size", "1G"]
     command: ["/swap.sh", "--path", "/var/external/swap", "--size", "1G", "--encrypt"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
   - name: rngd
-    image: linuxkit/rngd:v0.4
-trust:
-  org:
-    - linuxkit
-    - library
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd

examples/tpm.yml

@@ -1,30 +1,27 @@
 kernel:
-  image: linuxkit/kernel:4.9.38
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
   - name: tss
-    image: linuxkit/tss:v0.4
+    image: linuxkit/tss:856286012a613598d6ef6869b196f9a72245b7d2
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
 files:
   - path: etc/getty.shadow
     # sample sets password for root to "abcdefgh" (without quotes)
     contents: 'root:$6$6tPd2uhHrecCEKug$8mKfcgfwguP7f.BLdZsT1Wz7WIIJOBY1oUFHzIv9/O71M2J0EPdtFqFGTxB1UK5ejqQxRFQ.ZSG9YXR0SNsc11:17322:0:::::'
-trust:
-  org:
-    - linuxkit

examples/vmware.yml

@@ -1,34 +0,0 @@
-kernel:
-  image: linuxkit/kernel:4.14.40
-  cmdline: "console=tty0"
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
-onboot:
-  - name: sysctl
-    image: linuxkit/sysctl:v0.4
-services:
-  - name: getty
-    image: linuxkit/getty:v0.4
-    env:
-     - INSECURE=true
-  - name: rngd
-    image: linuxkit/rngd:v0.4
-  - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
-  - name: nginx
-    image: nginx:1.13.8-alpine
-    capabilities:
-     - CAP_NET_BIND_SERVICE
-     - CAP_CHOWN
-     - CAP_SETUID
-     - CAP_SETGID
-     - CAP_DAC_OVERRIDE
-    binds:
-     - /etc/resolv.conf:/etc/resolv.conf
-trust:
-  org:
-    - linuxkit
-    - library

examples/volumes.yml

@@ -0,0 +1,45 @@
+# example with volumes, both blank and populated
+kernel:
+  image: linuxkit/kernel:6.6.13
+  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
+init:
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
+onboot:
+  - name: sysctl
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
+  - name: dhcpcd
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
+    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
+onshutdown:
+  - name: shutdown
+    image: busybox:latest
+    command: ["/bin/echo", "so long and thanks for all the fish"]
+services:
+  - name: getty
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
+    env:
+     - INSECURE=true
+  - name: rngd
+    image: linuxkit/rngd:cdb919e4aee49fed0bf6075f0a104037cba83c39
+  - name: nginx
+    image: nginx:1.19.5-alpine
+    capabilities:
+     - CAP_NET_BIND_SERVICE
+     - CAP_CHOWN
+     - CAP_SETUID
+     - CAP_SETGID
+     - CAP_DAC_OVERRIDE
+    binds:
+     - /etc/resolv.conf:/etc/resolv.conf
+     - blank:/blank
+     - alpine:/alpine
+volumes:
+- name: blank   # blank volume
+- name: alpine  # populated volume
+  image: alpine:3.19
+files:
+  - path: etc/linuxkit-config
+    metadata: yaml

examples/vpnkit-forwarder.yml

@@ -1,16 +1,16 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=ttyS0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
 onboot:
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
   - name: mount-vpnkit
-    image: alpine:3.7
+    image: alpine:3.13
     binds:
         - /var/:/host_var:rbind,rshared
     capabilities:
@@ -19,9 +19,11 @@ onboot:
     command: ["sh", "-c", "mkdir /host_var/vpnkit && mount -v -t 9p -o trans=virtio,dfltuid=1001,dfltgid=50,version=9p2000 port /host_var/vpnkit"]
 services:
   - name: sshd
-    image: linuxkit/sshd:v0.4
+    image: linuxkit/sshd:75f399fbfb6455dfccd4cb30543d0b4b494d28c8
+    binds.add:
+      - /root/.ssh:/root/.ssh
   - name: vpnkit-forwarder
-    image: linuxkit/vpnkit-forwarder:v0.4
+    image: linuxkit/vpnkit-forwarder:a89ec807d7d675dccd53773c07382bc707db3396
     binds:
         - /var/vpnkit:/port
     net: host
@@ -32,7 +34,3 @@ files:
     source: ~/.ssh/id_rsa.pub
     mode: "0600"
     optional: true
-
-trust:
-  org:
-    - linuxkit

examples/vsudd-containerd.yml

@@ -1,22 +1,18 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=ttyS0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
 onboot:
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
 services:
   - name: vsudd
-    image: linuxkit/vsudd:v0.4
+    image: linuxkit/vsudd:b4d80d243733f80906cdbcf77f367a7b5744dc09
     binds:
         - /run/containerd/containerd.sock:/run/containerd/containerd.sock
     command: ["/vsudd",
         "-inport", "2374:unix:/run/containerd/containerd.sock"]
-
-trust:
-  org:
-    - linuxkit

examples/vultr.yml

@@ -1,41 +0,0 @@
-kernel:
-  image: linuxkit/kernel:4.14.40
-  cmdline: "console=ttyS0"
-init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
-onboot:
-  - name: sysctl
-    image: linuxkit/sysctl:v0.4
-  - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
-    command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
-  - name: metadata
-    image: linuxkit/metadata:v0.4
-services:
-  - name: getty
-    image: linuxkit/getty:v0.4
-    env:
-     - INSECURE=true
-  - name: rngd
-    image: linuxkit/rngd:v0.4
-  - name: sshd
-    image: linuxkit/sshd:v0.4
-    binds:
-     - /run/config/ssh/authorized_keys:/root/.ssh/authorized_keys
-  - name: nginx
-    image: nginx:1.13.8-alpine
-    capabilities:
-     - CAP_NET_BIND_SERVICE
-     - CAP_CHOWN
-     - CAP_SETUID
-     - CAP_SETGID
-     - CAP_DAC_OVERRIDE
-    binds:
-     - /etc/resolv.conf:/etc/resolv.conf
-trust:
-  org:
-    - linuxkit
-    - library

examples/wireguard.yml

@@ -1,19 +1,19 @@
 kernel:
-  image: linuxkit/kernel:4.14.40
+  image: linuxkit/kernel:6.6.13
   cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
 init:
-  - linuxkit/init:v0.4
-  - linuxkit/runc:v0.4
-  - linuxkit/containerd:v0.4
-  - linuxkit/ca-certificates:v0.4
+  - linuxkit/init:e120ea2a30d906bd1ee1874973d6e4b1403b5ca3
+  - linuxkit/runc:6062483d748609d505f2bcde4e52ee64a3329f5f
+  - linuxkit/containerd:39301e7312f13eedf19bd5d5551af7b37001d435
+  - linuxkit/ca-certificates:5aaa343474e5ac3ac01f8b917e82efb1063d80ff
 onboot:
   - name: sysctl
-    image: linuxkit/sysctl:v0.4
+    image: linuxkit/sysctl:5a374e4bf3e5a7deeacff6571d0f30f7ea8f56db
   - name: dhcpcd
-    image: linuxkit/dhcpcd:v0.4
+    image: linuxkit/dhcpcd:e9e3580f2de00e73e7b316a007186d22fea056ee
     command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf", "-1"]
   - name: wg0
-    image: linuxkit/ip:v0.4
+    image: linuxkit/ip:bb250017b05de5e16ac436b1eb19a39c87b5a252
     net: new
     binds:
       - /etc/wireguard:/etc/wireguard
@@ -26,7 +26,7 @@ onboot:
       bindNS:
           net: /run/netns/wg0
   - name: wg1
-    image: linuxkit/ip:v0.4
+    image: linuxkit/ip:bb250017b05de5e16ac436b1eb19a39c87b5a252
     net: new
     binds:
       - /etc/wireguard:/etc/wireguard
@@ -40,12 +40,12 @@ onboot:
           net: /run/netns/wg1
 services:
   - name: getty
-    image: linuxkit/getty:v0.4
+    image: linuxkit/getty:5d86a2ce2d890c14ab66b13638dcadf74f29218b
     env:
      - INSECURE=true
     net: /run/netns/wg1
   - name: rngd
-    image: linuxkit/rngd:v0.4
+    image: linuxkit/rngd:83a6481f04da73e710c1d416355920b8ff4dc1dd
   - name: nginx
     image: nginx:1.13.8-alpine
     net: /run/netns/wg0
@@ -77,7 +77,3 @@ files:
       PublicKey = AcS5t3PC5nL/oj0sYhc3yFpDlRaXoJ0mfEq6iq0rFF4=
       AllowedIPs = 0.0.0.0/0
       Endpoint = 127.0.0.1:51820
-trust:
-  org:
-    - linuxkit
-    - library

kernel/5.10.x/patches/0001-include-uapi-linux-swab-Fix-potentially-missing-__al.patch

@@ -0,0 +1,55 @@
+From 3635a8090f2271103511b68a5853b1d7e0a925b5 Mon Sep 17 00:00:00 2001
+From: Matt Redfearn <matt.redfearn@mips.com>
+Date: Wed, 3 Jan 2018 09:57:30 +0000
+Subject: [PATCH] include/uapi/linux/swab: Fix potentially missing
+ __always_inline
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+Commit bc27fb68aaad ("include/uapi/linux/byteorder, swab: force inlining
+of some byteswap operations") added __always_inline to swab functions
+and commit 283d75737837 ("uapi/linux/stddef.h: Provide __always_inline to
+userspace headers") added a definition of __always_inline for use in
+exported headers when the kernel's compiler.h is not available.
+
+However, since swab.h does not include stddef.h, if the header soup does
+not indirectly include it, the definition of __always_inline is missing,
+resulting in a compilation failure, which was observed compiling the
+perf tool using exported headers containing this commit:
+
+In file included from /usr/include/linux/byteorder/little_endian.h:12:0,
+                 from /usr/include/asm/byteorder.h:14,
+                 from tools/include/uapi/linux/perf_event.h:20,
+                 from perf.h:8,
+                 from builtin-bench.c:18:
+/usr/include/linux/swab.h:160:8: error: unknown type name ‘__always_inline’
+ static __always_inline __u16 __swab16p(const __u16 *p)
+
+Fix this by replacing the inclusion of linux/compiler.h with
+linux/stddef.h to ensure that we pick up that definition if required,
+without relying on it's indirect inclusion. compiler.h is then included
+indirectly, via stddef.h.
+
+Fixes: 283d75737837 ("uapi/linux/stddef.h: Provide __always_inline to userspace headers")
+Signed-off-by: Matt Redfearn <matt.redfearn@mips.com>
+---
+ include/uapi/linux/swab.h | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/include/uapi/linux/swab.h b/include/uapi/linux/swab.h
+index 7272f85d6d6a..3736f2fe1541 100644
+--- a/include/uapi/linux/swab.h
++++ b/include/uapi/linux/swab.h
+@@ -3,7 +3,7 @@
+ #define _UAPI_LINUX_SWAB_H
+ 
+ #include <linux/types.h>
+-#include <linux/compiler.h>
++#include <linux/stddef.h>
+ #include <asm/bitsperlong.h>
+ #include <asm/swab.h>
+ 
+-- 
+2.26.2
+