Merge pull request #1597 from justincormack/linuxkit

Rename Moby to LinuxKit part 1

README.md

@@ -1,6 +1,6 @@
-# Moby
+# LinuxKit
 
-Moby, a toolkit for building custom minimal, immutable Linux distributions.
+LinuxKit, a toolkit for building custom minimal, immutable Linux distributions.
 
 - Secure defaults without compromising usability
 - Everything is replaceable and customisable
@@ -17,15 +17,16 @@ Moby, a toolkit for building custom minimal, immutable Linux distributions.
 
 ### Build the `moby` tool
 
-Simple build instructions: use `make` to build. This will build the Moby customisation tool. 
+Simple build instructions: use `make` to build. This will build the customisation tool in `bin/`. Add this
+to your `PATH` or copy it to somewhere in your `PATH` eg `sudo cp bin/moby /usr/local/bin/`.
 
 If you already have `go` installed you can use `go get -u github.com/docker/moby/src/cmd/moby` to install
-the `moby` tool, and then use `moby build moby.yml` to build the example configuration. You
+the `moby` tool, and then use `moby build linuxkit.yml` to build the example configuration. You
 can use `go get -u github.com/docker/moby/src/cmd/infrakit-instance-hyperkit` to get the
 hyperkit infrakit tool.
 
-Once you have built the tool, use `bin/moby build moby.yml` to build the example configuration,
+Once you have built the tool, use `moby build linuxkit.yml` to build the example configuration,
-and `bin/moby run moby` to run locally. Use `halt` to terminate on the console.
+and `bin/moby run linuxkit` to run locally. Use `halt` to terminate on the console.
 
 Build requirements:
 - GNU `make`
@@ -34,14 +35,14 @@ Build requirements:
 
 ### Booting and Testing
 
-You can use `bin/moby run <name>` to execute the image you created with `moby build <name>.yml`.
+You can use `moby run <name>` to execute the image you created with `moby build <name>.yml`.
 This will use a suitable backend for your platform or you can choose one, for example VMWare.
 See `moby run --help`.
 
 Some platforms do not yet have `moby run` support, so you can use `./scripts/qemu.sh moby-initrd.img moby-bzImage moby-cmdline`
 or `./scripts/qemu.sh mobylinux-bios.iso` which runs qemu in a Docker container.
 
-`make test` or `make hyperkit-test` will run the test suite
+`make test` or `make test-hyperkit` will run the test suite
 
 There are also docs for booting on [Google Cloud](docs/gcp.md); `./bin/moby run --gcp <name>.yml` should
 work if you specified a GCP image to be built in the config.
@@ -50,9 +51,8 @@ More detailed docs will be available shortly, for running both single hosts and
 
 ## Building your own customised image
 
-To customise, copy or modify the [`moby.yml`](moby.yml) to your own `file.yml` or use one of the [examples](examples/) and then run `./bin/moby build file.yml` to
+To customise, copy or modify the [`linuxkit.yml`](linuxkit.yml) to your own `file.yml` or use one of the [examples](examples/) and then run `moby build file.yml` to
-generate its specified output. You can run the output with `./scripts/qemu.sh` or on OSX with `./bin/moby run file`. `moby run` targets will be available for other
+generate its specified output. You can run the output with `moby run file`.
-platforms shortly.
 
 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. It also specifies what
 formats to output, such as bootable ISOs and images for various platforms.
@@ -61,8 +61,8 @@ formats to output, such as bootable ISOs and images for various platforms.
 
 The yaml format specifies the image to be built:
 
-- `kernel` specifies a kernel Docker image, containing a kernel and a filesystem tarball, eg containing modules. `mobylinux/kernel` is built from `kernel/`
+- `kernel` specifies a kernel Docker image, containing a kernel and a filesystem tarball, eg containing modules. The example kernels are built from `kernel/`
-- `init` is the base `init` process Docker image, which is unpacked as the base system, containing `init`, `containerd`, `runc` and a few tools. Built from `base/init/`
+- `init` is the base `init` process Docker image, which is unpacked as the base system, containing `init`, `containerd`, `runc` and a few tools. Built from `pkg/init/`
 - `onboot` are the system containers, executed sequentially in order. They should terminate quickly when done.
 - `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
@@ -70,13 +70,10 @@ The yaml format specifies the image to be built:
 
 For a more detailed overview of the options see [yaml documentation](docs/yaml.md).
 
-## Architecture
+## Architecture and security
 
 There is an [overview of the architecture](docs/architecture.md) covering how the system works.
 
-
-## Security design
-
 There is an [overview of the security considerations and direction](docs/security.md) covering the security design of the system.
 
 ## Roadmap

docs/containerd.md

@@ -1,27 +0,0 @@
-## Using the system containerd
-
-Here is a simple example script that will run a container using the system containerd.
-
-You should run it from `/var` as the root filesystem is in RAM, and will use up memory.
-
-```bash
-#!/bin/sh
-
-NAME=nginx
-VERSION=latest
-
-docker pull ${NAME}:${VERSION}
-CONTAINER=$(docker create --net=host --security-opt apparmor=unconfined --cap-drop all --cap-add net_bind_service --oom-score-adj=-500 -v /var/log/nginx:/var/log/nginx -v /var/cache/nginx:/var/cache/nginx -v /var/run:/var/run ${NAME}:${VERSION})
-docker run -v ${PWD}:/conf -v /var/run/docker.sock:/var/run/docker.sock --rm jess/riddler -f -bundle /conf ${CONTAINER}
-rm -rf rootfs && mkdir rootfs
-docker export ${CONTAINER} | tar -C rootfs -xf -
-docker rm ${CONTAINER}
-
-mkdir -p /var/log/nginx /var/cache/nginx
-
-containerd-ctr containers start ${NAME} .
-containerd-ctr containers
-```
-
-For production, you will want to create the `config.json` offline and bundle it in with your
-init script, but you can create the rootfs online.

docs/faq.md

@@ -4,7 +4,7 @@ Please open an issue if you want to add a question here.
 
 ## How do updates work?
 
-Moby does not require being installed on a disk, it is often run from an ISO, PXE or other
+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 
 system is installed, and it would be useful to support this for that use case, and an

docs/gcp.md

@@ -1,6 +1,7 @@
-# Using Moby on Google Cloud Platform (GCP)
+# Using LinuxKit on Google Cloud Platform (GCP)
 
-This is a quick guide to run Moby on GCP.
+This is a quick guide to run LinuxKit on GCP. A lot of internal development and CI
+has used Google Cloud so the support is very good; other platforms will have similar support soon.
 
 ## Setup
 
@@ -38,11 +39,11 @@ to create a Service Account.
 
 Make sure to download the credentials in JSON format and store them somewhere safe.
 
-## Build a moby image
+## Build an image
 
 Add a `gcp` output line to your yaml config, see the example in `examples/gcp.yml`.
 
-Then do `./bin/moby myfile.yml`
+Then do `moby build myfile.yml`
 
 This will create a local `myfile.img.tar.gz` compressed image file, upload it to the
 specified bucket, and create a bootable image.

docs/hub.md

@@ -1,30 +0,0 @@
-## Docker Hub
-
-There are images on Docker Hub to help with reproducible builds. These are built (by hand) from `alpine/base`,
-generally with tags based on the image contents.
-
-- `mobylinux/alpine-base` the base packages for Moby, before we add Docker and our code and config
-- `mobylinux/alpine-build-c` for building C code
-- `mobylinux/mkimage-iso-bios` for building BIOS image
-- `mobylinux/alpine-efi` for building efi images
-- `mobylinux/alpine-qemu` for Qemu eg for the tests
-- `mobylinux/go-compile` for building Go code
-
-
-The `Dockerfile`s for these are under `alpine/base`. To update, modify the `Dockerfile` if you wish
-to change the packages used, and `repositories` if needed, and run `make`. This will push the image
-to Docker Hub if it has changed.
-
-To update `packages` to use the new version, update their respective `Dockerfile`. Make sure you also update the `# TAG: ` comment at the start of the file.  Both the `TAG` and the `sha256` are printed out when pushing the update base to the hub.
-
-For example, `alpine/base/alpine-base` is the image used to build the Moby image itself, which is
-used in `alpine/Dockerfile`. The uploaded tags can be seen at [Docker Hub](https://hub.docker.com/r/mobylinux/alpine-base/tags/).
-
-In addition
-- `mobylinux/media` contains build artifacts
-
-You can upload build artifacts with `make media` or `make media MEDIA_PREFIX=1.12.0-` if you want to change the prefix of the git hash.
-The will by default be prefixed by `experimental-` if they are Docker experimental builds. These are used in the Mac and Windows build
-process to get the images.
-
-Ping @justincormack if you need access to the Hub organization.

docs/infrakit.md

@@ -1,9 +1,9 @@
-## Hyperkit/Moby Infrakit plugin
+## Hyperkit Infrakit plugin
 
-There is a HyperKit Moby instance plugin for infrakit in
+There is a HyperKit instance plugin for infrakit in
 `src/cmd/infrakit-instance-hyperkit`. The instance plugin is capable
 to start/manage several hyperkit instances with with different
-configurations and Moby configurations.
+configurations and LinuxKit configurations.
 
 The plugin keeps state in a local directory (default
 `.infrakit/hyperkit-vms`) where each instance keeps some state in a
@@ -35,7 +35,7 @@ Then start the hyperkit plugin:
 ./bin/infrakit-instance-hyperkit
 ```
 
-Next, you can commit a new configuration. There is a sample infrakit config file in `hyperkit.json`. It assumes that you have a default moby build in the top-level directory. The `Moby` property needs to be of the form `<dir>/<prefix>` and assumes that the kernel and initrd images are called `<prefix>-bzImage` and `<prefix>-initrd.img` respectively (this is the convention used by the `moby` tool).
+Next, you can commit a new configuration. There is a sample infrakit config file in `hyperkit.json`. It assumes that you have a default LinuxKit build in the top-level directory. The `Moby` property needs to be of the form `<dir>/<prefix>` and assumes that the kernel and initrd images are called `<prefix>-bzImage` and `<prefix>-initrd.img` respectively (this is the convention used by the `moby` tool).
 ```
 infrakit group commit hyperkit.json
 ```
@@ -48,4 +48,3 @@ If you kill the hyperkit process a new instance will be restarted. If
 you change the VM parameter in JSON file and commit the new config, a
 new VM will be created. f you change the `Size` parameter, multiple
 VMs will get started.
-

docs/kernel-patches.md

@@ -1,6 +1,6 @@
-# Working with Linux kernel patches for Moby
+# Working with Linux kernel patches for LinuxKit
 
-We may apply patches to the Linux kernel used in Moby, primarily to
+We may apply patches to the Linux kernel used in LinuxKit, primarily to
 cherry-pick some upstream patches or to add some additional
 functionality, not yet accepted upstream.
 
@@ -32,14 +32,14 @@ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
 ```
 
 We use the following variables:
-- `MOBYSRC`: Base directory of Moby Linux repository
+- `KITSRC`: Base directory of LinuxKit repository
 - `LINUXSRC`: Base directory of Linux stable kernel repository
 e.g.:
 ```sh
-MOBYSRC=~/src/docker/moby
+KITSRC=~/src/docker/linuxkit
 LINUXSRC=~/src/docker/linux-stable
 ```
-to refer to the location of the Moby and Linux kernel trees.
+to refer to the location of the LinuxKit and Linux kernel trees.
 
 
 # Updating the patches to a new kernel version
@@ -54,7 +54,7 @@ If you don't already have a branch, it's best to import the current patch set an
 ```sh
 cd $LINUXSRC
 git checkout -b ${NEWTAG}-moby ${CURTAG}
-git am ${MOBYSRC}/kernel/patches/*.patch
+git am ${KITSRC}/kernel/patches/*.patch
 git rebase ${NEWTAG}-moby ${NEWTAG}
 ```
 
@@ -82,13 +82,13 @@ DCO lines, e.g.:
 Origin: https://patchwork.ozlabs.org/patch/622404/
 ```
 
-# Export patches to moby
+# Export patches to LinuxKit
 
-To export patches to Moby, you should use `git format-patch` from the Linux tree, e.g., something along these lines:
+To export patches to LinuxKit, you should use `git format-patch` from the Linux tree, e.g., something along these lines:
 ```sh
 cd $LINUXSRC
-rm $MOBYSRC/kernel/patches-4.9/*
+rm $KITSRC/kernel/patches-4.9/*
-git format-patch -o $MOBYSRC/kernel/patches-4.9 v4.9.15..HEAD
+git format-patch -o $KITSRC/kernel/patches-4.9 v4.9.15..HEAD
 ```
 
 The, create a PR for Moby.

docs/platforms.md

@@ -1,42 +0,0 @@
-## List of platforms
-
-These are the supported platforms. Each should boot with `mobyplatform=xxx` in the command line.
-
-### Desktop
-`mac` `windows` https://github.com/docker/pinata
-
-The desktop editions.
-
-### Cloud
-`aws` `azure` https://github.com/docker/editions
-
-The cloud editions
-
-### Test
-`test` https://github.com/docker/moby
-
-Internal test target
-
-### Running on other platforms
-`unknown`
-
-The default fallback target name is `unknown` that does only default setup.
-
-## Notes on other platforms
-
-KVM/machine: https://github.com/docker/moby/pull/225
-
-Xen PV: a suitable config is
-```
-name = "moby0"
-memory = 1024
-vcpus=1
-disk = ['phy:/dev/vg0/moby0,hda,w']
-vif = [ 'mac=00:22:ab:42:99:00, bridge=br0' ]
-kernel="/home/justin/images/moby/vmlinuz64"
-ramdisk="/home/justin/images/moby/initrd.img.gz"
-extra="console=hvc0"
-on_reboot="restart"
-```
-
-VMWare Fusion: Should work fine, IDE, SATA or SCSI disks will work, and the default network driver.

docs/security-events.md

@@ -1,13 +1,13 @@
-# Moby Security Events
+# LinuxKit Security Events
 
-The incomplete list below is an assessment of some CVEs, and Moby's resilience
+The incomplete list below is an assessment of some CVEs, and LinuxKit's resilience
 (or not) to them.
 
 ### Bugs mitigated:
 
 * [CVE-2017-2636](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-2636)
   ([exploit post](https://a13xp0p0v.github.io/2017/03/24/CVE-2017-2636.html)):
-  This CVE requires `CONFIG_N_HDLC={y|m}`, which Moby does not specify, and so
+  This CVE requires `CONFIG_N_HDLC={y|m}`, which LinuxKit does not specify, and so
   is not vulnerable.
 
 ### Bugs not mitigated:

docs/security.md

@@ -1,37 +1,37 @@
 # Security Design
 
-Moby is architected to be secure by default. This document intends to detail the design decisions behind Moby that
+LinuxKit is architected to be secure by default. This document intends to detail the design decisions behind LinuxKit that
 pertain to security, as well as provide context for future project direction.
 
 
 ## Modern and Securely Configured Kernels
 
-Moby uses modern kernels, and updates frequently following new releases. It is well understood that many kernel bugs
+LinuxKit uses modern kernels, and updates frequently following new releases. It is well understood that many kernel bugs
 may lurk in the [codebase for years](https://lwn.net/Articles/410606/). Therefore, it is imperative to not only patch
 the kernel to fix individual vulnerabilities but also benefit from the upstream security measures designed to prevent
 classes of kernel bugs.
 
-In practice this means Moby tracks new kernel releases very closely, and also follows best practice settings for the
+In practice this means LinuxKit tracks new kernel releases very closely, and also follows best practice settings for the
 kernel configuration from the [Kernel Self Protection Project](https://kernsec.org/wiki/index.php/Kernel_Self_Protection_Project)
 and elsewhere.
 
-The Moby project maintainers are actively collaborating with KSPP and it is an established [priority for the project](../projects/kspp/roadmap.md).
+The LinuxKit project maintainers are actively collaborating with KSPP and it is an established [priority for the project](../projects/kspp/roadmap.md).
 
-The Moby kernel is intended to be identical to the upstream kernel - We only intend to carry patches that are on track
+The LinuxKit kernel is intended to be identical to the upstream kernel - We only intend to carry patches that are on track
 to be upstreamed, or fix regressions or bugs and that we will upstream.
 
 
 ## Minimal Base
 
-Moby is not a full host operating system, as it primarily has two jobs: run `containerd` containers, and be secure.
+LinuxKit is not a full host operating system, as it primarily has two jobs: run `containerd` containers, and be secure.
 
-As such, the system does not contain extraneous packages or drivers by default. Because Moby is customizable, it is up to
+As such, the system does not contain extraneous packages or drivers by default. Because LinuxKit is customizable, it is up to
 individual operators to include any additional bits they may require.
 
 
 ## Type Safe System Daemons
 
-The core system components that we must include in Moby userspace are key to security, and we believe
+The core system components that we must include in LinuxKit userspace are key to security, and we believe
 they should be written in type safe languages, such as [Rust](https://www.rust-lang.org/en-US/), [Go](https://golang.org/)
 and [OCaml](http://www.ocaml.org/), and run with maximum privilege separation and isolation.
 
@@ -46,50 +46,50 @@ and namespaced separately from the host as appropriate.
 
 ## Built With Hardened Toolchains and Containers
 
-Moby's build process heavily leverages Docker images for packaging. Of note, all intermediate build images
+LinuxKit's build process heavily leverages Docker images for packaging. Of note, all intermediate build images
-are referenced by digest to ensures reproducibility across Moby builds. Tags are mutable, and thus subject to override
+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 Moby's buildchain.
+(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 Moby maintainers using [Docker Content Trust](https://docs.docker.com/engine/security/trust/content_trust/),
+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, Moby's build process leverages [Alpine Linux's](https://alpinelinux.org/) hardened userspace tools such as
+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
 are also PIE.
 
 
 ## Immutable Infrastructure
 
-Moby runs as an initramfs and its system containers are baked in at build-time, essentially making Moby immutable.
+LinuxKit runs as an initramfs and its system containers are baked in at build-time, essentially making LinuxKit immutable.
 
-Moreover, Moby has a read-only root filesystem: system configuration and sensitive files cannot be modified after boot.
+Moreover, LinuxKit has a read-only root filesystem: system configuration and sensitive files cannot be modified after boot.
-The only files on Moby that are allowed to be modified pertain to namespaced container data and stateful partitions.
+The only files on LinuxKit that are allowed to be modified pertain to namespaced container data and stateful partitions.
 
-As such, Moby access to the Moby base system is limited in scope: in the event of any container escape, the attack surface
+As such, access to the LinuxKit base system is limited in scope: in the event of any container escape, the attack surface
-is also limited because the system binaries and configuration is unmodifiable. To that end, the Moby base system does not
+is also limited because the system binaries and configuration is unmodifiable. To that end, the LinuxKit base system does not
 supply a package manger: containers must be built beforehand with the dependencies they require.
 
-Once a secure Moby base system has been built, it cannot be tampered with, even by malicious user containers. Even if user
+Once a secure LinuxKit base system has been built, it cannot be tampered with, even by malicious user containers. Even if user
-containers unintentionally expose themselves to attack vectors, immutability of the Moby base system limits the scope of
+containers unintentionally expose themselves to attack vectors, immutability of the LinuxKit base system limits the scope of
 host attack.
 
 
 ## External Updates - Trusted Provisioning
 
-Following the principle of least privilege for immutable infrastructure, Moby cannot have the ability or attack surface 
+Following the principle of least privilege for immutable infrastructure, LinuxKit cannot have the ability or attack surface 
 to update itself. It is the responsibility of an external system, most commonly [infrakit](https://github.com/docker/infrakit), to provision
-and update Moby nodes.
+and update LinuxKit nodes.
 
-It is encouraged to consider the notion of "reverse uptime" when deploying Moby - because Moby is immutable, it should be
+It is encouraged to consider the notion of "reverse uptime" when deploying LinuxKit - because LinuxKit is immutable, it should be
-acceptable and encouraged to frequently redeploy Moby nodes.
+acceptable and encouraged to frequently redeploy LinuxKit nodes.
 
-Moby cannot make any trusted hardware assumptions because of the vast variety of platforms it boots on, but Infrakit
+LinuxKit cannot make any trusted hardware assumptions because of the vast variety of platforms it boots on, but Infrakit
-can be used to provide trusted boot information and integrate with existing trusted boot hardware. In this sense, Moby is
+can be used to provide trusted boot information and integrate with existing trusted boot hardware. In this sense, LinuxKit is
 "trusted boot-ready" and the team is already collaborating with cloud and hardware providers to make this a reality.
 
 
 ## Incubating Next-generation Security Projects
 
-Since Moby is meant to only run containers and be secure, it is the perfect platform to incubate new (and potentially radical!)
+Since LinuxKit is meant to only run containers and be secure, it is the perfect platform to incubate new (and potentially radical!)
 paradigms and strategies for securing the Linux kernel - allowing them to be used in production environments and attract
 critical mass before eventually being upstreamed.
 
@@ -98,4 +98,4 @@ In this spirit, the [`/projects`](../projects) subdirectory houses a number of s
 like the [Noise protocol framework](http://www.noiseprotocol.org/)
 - [okernel](../projects/okernel/README.md): a mechanism to split the kernel into inner and outer subkernels with different trust properties
 
-The Moby community welcomes new security projects - please propose a new project if you have one you'd like to include!
+The LinuxKit community welcomes new security projects - please propose a new project if you have one you'd like to include!

docs/vendoring.md

@@ -1,4 +1,4 @@
-vendoring
+Vendoring
 =========
 
 The Go code in this repo depends on a number of Go libraries.