diff --git a/Documentation/getting-started-rkt.md b/Documentation/getting-started-rkt.md index 1624f6d4..aad3f52d 100644 --- a/Documentation/getting-started-rkt.md +++ b/Documentation/getting-started-rkt.md @@ -6,7 +6,7 @@ In this tutorial, we'll run `matchbox` on your Linux machine with `rkt` and `CNI ## Requirements -Install [rkt](https://coreos.com/rkt/docs/latest/distributions.html) 1.8 or higher ([example script](https://github.com/dghubble/phoenix/blob/master/fedora/sources.sh)) and setup rkt [privilege separation](https://coreos.com/rkt/docs/latest/trying-out-rkt.html). +Install [rkt](https://coreos.com/rkt/docs/latest/distributions.html) 1.12.0 or higher ([example script](https://github.com/dghubble/phoenix/blob/master/fedora/sources.sh)) and setup rkt [privilege separation](https://coreos.com/rkt/docs/latest/trying-out-rkt.html). Next, install the package dependencies. @@ -33,6 +33,8 @@ Download CoreOS image assets referenced by the `etcd` [example](../examples) to $ ./scripts/get-coreos stable 1235.9.0 ./examples/assets ``` +## Network + Define the `metal0` virtual bridge with [CNI](https://github.com/appc/cni). ```bash @@ -57,11 +59,10 @@ On Fedora, add the `metal0` interface to the trusted zone in your firewall confi ```sh $ sudo firewall-cmd --add-interface=metal0 --zone=trusted +$ sudo firewall-cmd --add-interface=metal0 --zone=trusted --permanent ``` -After a recent update, you may see a warning that NetworkManager controls the interface. Work-around this using the firewall-config GUI to add `metal0` to the trusted zone. - -For development convenience, add `/etc/hosts` entries for nodes so they may be referenced by name as you would in production. +For development convenience, you may wish to add `/etc/hosts` entries for nodes to refer to them by name. ``` # /etc/hosts @@ -71,21 +72,11 @@ For development convenience, add `/etc/hosts` entries for nodes so they may be r 172.18.0.23 node3.example.com ``` -Trust the needed ACIs. - ## Containers Run the `matchbox` and `dnsmasq` services on the `metal0` bridge. `dnsmasq` will run DHCP, DNS, and TFTP services to create a suitable network boot environment. `matchbox` will serve provisioning configs to machines on the network which attempt to PXE boot. -Trust the needed ACIs. - -```sh -$ sudo rkt trust --prefix quay.io/coreos/matchbox -$ sudo rkt trust --prefix quay.io/coreos/alpine-sh -$ sudo rkt trust --prefix coreos.com/dnsmasq -``` - -The `devnet` wrapper script can quickly rkt run `matchbox` and `dnsmasq` in systemd transient units. Create can take the name of any example cluster in [examples](../examples). +The `devnet` wrapper script rkt runs `matchbox` and `dnsmasq` in systemd transient units. Create can take the name of any example cluster in [examples](../examples). ```sh $ sudo ./scripts/devnet create etcd3 @@ -94,9 +85,7 @@ $ sudo ./scripts/devnet create etcd3 Inspect the journal logs or check the status of the systemd services. ``` -# quick status $ sudo ./scripts/devnet status -# tail logs $ journalctl -f -u dev-matchbox $ journalctl -f -u dev-dnsmasq ``` @@ -109,13 +98,23 @@ Take a look at the [etcd3 groups](../examples/groups/etcd3) to get an idea of ho ### Manual -If you prefer to start the containers yourself, instead of using `devnet`: +If you prefer to start the containers yourself, instead of using `devnet`, +```sh +sudo rkt run --net=metal0:IP=172.18.0.2 \ + --mount volume=data,target=/var/lib/matchbox \ + --volume data,kind=host,source=$PWD/examples \ + --mount volume=groups,target=/var/lib/matchbox/groups \ + --volume groups,kind=host,source=$PWD/examples/groups/etcd3 \ + quay.io/coreos/matchbox:v0.5.0 -- -address=0.0.0.0:8080 -log-level=debug ``` -# matchbox with etcd3 example -$ sudo rkt run --net=metal0:IP=172.18.0.2 --mount volume=data,target=/var/lib/matchbox --volume data,kind=host,source=$PWD/examples --mount volume=groups,target=/var/lib/matchbox/groups --volume groups,kind=host,source=$PWD/examples/groups/etcd3 quay.io/coreos/matchbox:latest -- -address=0.0.0.0:8080 -log-level=debug -# dnsmasq -$ sudo rkt run coreos.com/dnsmasq:v0.3.0 --net=metal0:IP=172.18.0.3 --mount volume=config,target=/etc/dnsmasq.conf --volume config,kind=host,source=$PWD/contrib/dnsmasq/metal0.conf +```sh +sudo rkt run --net=metal0:IP=172.18.0.3 \ + --dns=host \ + --mount volume=config,target=/etc/dnsmasq.conf \ + --volume config,kind=host,source=$PWD/contrib/dnsmasq/metal0.conf \ + quay.io/coreos/dnsmasq:v0.4.0 \ + --caps-retain=CAP_NET_ADMIN,CAP_NET_BIND_SERVICE ``` If you get an error about the IP assignment, stop old pods and run garbage collection. diff --git a/Documentation/grub.md b/Documentation/grub.md index 968b55cb..334c293c 100644 --- a/Documentation/grub.md +++ b/Documentation/grub.md @@ -1,4 +1,3 @@ - # GRUB2 netboot Use GRUB to network boot UEFI hardware. @@ -23,10 +22,25 @@ On Fedora, add the `metal0` interface to the trusted zone in your firewall confi $ sudo firewall-cmd --add-interface=metal0 --zone=trusted ``` -Run the `coreos.com/dnsmasq` ACI with rkt. +Run the `quay.io/coreos/dnsmasq` container image with rkt or docker. ```sh -$ sudo rkt run coreos.com/dnsmasq:v0.3.0 --net=metal0:IP=172.18.0.3 -- -d -q --dhcp-range=172.18.0.50,172.18.0.99 --enable-tftp --tftp-root=/var/lib/tftpboot --dhcp-match=set:efi-bc,option:client-arch,7 --dhcp-boot=tag:efi-bc,grub.efi --dhcp-userclass=set:grub,GRUB2 --dhcp-boot=tag:grub,"(http;matchbox.foo:8080)/grub","172.18.0.2" --log-queries --log-dhcp --dhcp-userclass=set:ipxe,iPXE --dhcp-boot=tag:pxe,undionly.kpxe --dhcp-boot=tag:ipxe,http://matchbox.foo:8080/boot.ipxe --address=/matchbox.foo/172.18.0.2 +sudo rkt run --net=metal0:IP=172.18.0.3 quay.io/coreos/dnsmasq \ + --caps-retain=CAP_NET_ADMIN,CAP_NET_BIND_SERVICE \ + -- -d -q \ + --dhcp-range=172.18.0.50,172.18.0.99 \ + --enable-tftp \ + --tftp-root=/var/lib/tftpboot \ + --dhcp-match=set:efi-bc,option:client-arch,7 \ + --dhcp-boot=tag:efi-bc,grub.efi \ + --dhcp-userclass=set:grub,GRUB2 \ + --dhcp-boot=tag:grub,"(http;matchbox.example.com:8080)/grub","172.18.0.2" \ + --log-queries \ + --log-dhcp \ + --dhcp-userclass=set:ipxe,iPXE \ + --dhcp-boot=tag:pxe,undionly.kpxe \ + --dhcp-boot=tag:ipxe,http://matchbox.example.com:8080/boot.ipxe \ + --address=/matchbox.foo/172.18.0.2 ``` ## Client VM diff --git a/Documentation/network-setup.md b/Documentation/network-setup.md index 0548eafc..590a259b 100644 --- a/Documentation/network-setup.md +++ b/Documentation/network-setup.md @@ -46,31 +46,16 @@ address=/matchbox.foo/172.18.0.2 ## iPXE -Servers with DHCP/TFTP/ services which already network boot iPXE clients can use the `chain` command to make clients download and execute the iPXE boot script from `matchbox`. +Networks which already run DHCP and TFTP services to network boot PXE/iPXE clients can add an iPXE config to delegate or `chain` to the matchbox service's iPXE entrypoint. ``` # /var/www/html/ipxe/default.ipxe chain http://matchbox.foo:8080/boot.ipxe ``` -You can chainload from a menu entry or use other [iPXE commands](http://ipxe.org/cmd) if you have needs beyond just delegating to the iPXE script served by `matchbox`. +You can chainload from a menu entry or use other [iPXE commands](http://ipxe.org/cmd) if you need to do more than simple delegation. -## GRUB - -Needs more docs. - -`grub-mknetdir --net-directory=/var/lib/tftpboot` - -/var/lib/tftpboot/boot/grub/grub.cfg: -```ini -insmod i386-pc/http.mod -set root=http,matchbox.foo:8080 -configfile /grub -``` - -Make sure to replace variables in the example config files; instead of iPXE variables, use GRUB variables. Check the [GRUB2 manual](https://www.gnu.org/software/grub/manual/grub.html#Network). - -### Configuring DHCP +### PXE-enabled DHCP Configure your DHCP server to supply options to older PXE client firmware to specify the location of an iPXE or GRUB network boot program on your TFTP server. Send clients to the `matchbox` iPXE script or GRUB config endpoints. @@ -109,9 +94,11 @@ $ sudo firewall-cmd --add-service=dhcp --add-service=tftp [--add-service=dns] $ sudo firewall-cmd --list-services ``` -#### proxy DHCP +See [dnsmasq](#coreosdnsmasq) below to run dnsmasq with a container. -Alternately, a DHCP proxy server can be run alongside an existing non-PXE DHCP server. The proxy DHCP server provides only the next server and boot filename Options, leaving IP allocation to the DHCP server. Clients listen for both DHCP offers and merge the responses as though they had come from one PXE-enabled DHCP server. +#### Proxy-DHCP + +Alternately, a proxy-DHCP server can be run alongside an existing non-PXE DHCP server. The proxy DHCP server provides only the next server and boot filename Options, leaving IP allocation to the DHCP server. Clients listen for both DHCP offers and merge the responses as though they had come from one PXE-enabled DHCP server. Example `/etc/dnsmasq.conf`: @@ -141,21 +128,11 @@ $ sudo firewall-cmd --add-service=dhcp --add-service=tftp [--add-service=dns] $ sudo firewall-cmd --list-services ``` -With rkt: - -```sh -$ sudo rkt run coreos.com/dnsmasq:v0.3.0 --net=host -- -d -q --dhcp-range=192.168.1.1,proxy,255.255.255.0 --enable-tftp --tftp-root=/var/lib/tftpboot --dhcp-userclass=set:ipxe,iPXE --pxe-service=tag:#ipxe,x86PC,"PXE chainload to iPXE",undionly.kpxe --pxe-service=tag:ipxe,x86PC,"iPXE",http://matchbox.foo:8080/boot.ipxe --log-queries --log-dhcp -``` - -With Docker: - -```sh -$ sudo docker run --net=host --rm --cap-add=NET_ADMIN quay.io/coreos/dnsmasq -d -q --dhcp-range=192.168.1.1,proxy,255.255.255.0 --enable-tftp --tftp-root=/var/lib/tftpboot --dhcp-userclass=set:ipxe,iPXE --pxe-service=tag:#ipxe,x86PC,"PXE chainload to iPXE",undionly.kpxe --pxe-service=tag:ipxe,x86PC,"iPXE",http://matchbox.foo:8080/boot.ipxe --log-queries --log-dhcp -``` +See [dnsmasq](#coreosdnsmasq) below to run dnsmasq with a container. ### Configurable TFTP -If your DHCP server is configured to PXE boot clients, but you don't have control over this configuration, you can modify the pxelinux.cfg's served to PXE clients. +If your DHCP server is configured to network boot PXE clients (but not iPXE clients), add a pxelinux.cfg to serve an iPXE kernel image and append commands. Example `/var/lib/tftpboot/pxelinux.cfg/default`: @@ -171,31 +148,84 @@ Add ipxe.lkrn to `/var/lib/tftpboot` (see [iPXE docs](http://ipxe.org/embed)). ## coreos/dnsmasq -On networks without network services, the `coreos.com/dnsmasq:v0.3.0` rkt ACI or `coreos/dnsmasq:latest` Docker image can setup an appropriate environment quickly. The images bundle `undionly.kpxe` and `grub.efi` for convenience. Here are some examples which run a DHCP/TFTP/DNS server on your host's network: +The [quay.io/coreos/dnsmasq](https://quay.io/repository/coreos/dnsmasq) container image can run DHCP, TFTP, and DNS services via rkt or docker. The image bundles `undionly.kpxe` and `grub.efi` for convenience. See [contrib/dnsmasq](contrib/dnsmasq) for details. -With rkt: +Run DHCP, TFTP, and DNS on the host's network: ```sh -$ sudo rkt trust --prefix coreos.com/dnsmasq -# gpg key fingerprint is: 18AD 5014 C99E F7E3 BA5F 6CE9 50BD D3E0 FC8A 365E +sudo rkt run --net=host quay.io/coreos/dnsmasq \ + --caps-retain=CAP_NET_ADMIN,CAP_NET_BIND_SERVICE \ + -- -d -q \ + --dhcp-range=192.168.1.3,192.168.1.254 \ + --enable-tftp \ + --tftp-root=/var/lib/tftpboot \ + --dhcp-userclass=set:ipxe,iPXE \ + --dhcp-boot=tag:#ipxe,undionly.kpxe \ + --dhcp-boot=tag:ipxe,http://matchbox.example.com:8080/boot.ipxe \ + --address=/matchbox.example.com/192.168.1.2 \ + --log-queries \ + --log-dhcp ``` +```sh +sudo docker run --rm --cap-add=NET_ADMIN --net=host quay.io/coreos/dnsmasq \ + -d -q \ + --dhcp-range=192.168.1.3,192.168.1.254 \ + --enable-tftp --tftp-root=/var/lib/tftpboot \ + --dhcp-userclass=set:ipxe,iPXE \ + --dhcp-boot=tag:#ipxe,undionly.kpxe \ + --dhcp-boot=tag:ipxe,http://matchbox.example.com:8080/boot.ipxe \ + --address=/matchbox.example/192.168.1.2 \ + --log-queries \ + --log-dhcp +``` + +Run a proxy-DHCP and TFTP service on the host's network: ```sh -$ sudo rkt run coreos.com/dnsmasq:v0.3.0 --net=host -- -d -q --dhcp-range=192.168.1.3,192.168.1.254 --enable-tftp --tftp-root=/var/lib/tftpboot --dhcp-userclass=set:ipxe,iPXE --dhcp-boot=tag:#ipxe,undionly.kpxe --dhcp-boot=tag:ipxe,http://matchbox.foo:8080/boot.ipxe --address=/matchbox.foo/192.168.1.2 --log-queries --log-dhcp +sudo rkt run --net=host quay.io/coreos/dnsmasq \ + --caps-retain=CAP_NET_ADMIN,CAP_NET_BIND_SERVICE \ + -- -d -q \ + --dhcp-range=192.168.1.1,proxy,255.255.255.0 \ + --enable-tftp --tftp-root=/var/lib/tftpboot \ + --dhcp-userclass=set:ipxe,iPXE \ + --pxe-service=tag:#ipxe,x86PC,"PXE chainload to iPXE",undionly.kpxe \ + --pxe-service=tag:ipxe,x86PC,"iPXE",http://matchbox.example.com:8080/boot.ipxe \ + --log-queries \ + --log-dhcp ``` - -With Docker: - ```sh -$ sudo docker run --rm --cap-add=NET_ADMIN --net=host quay.io/coreos/dnsmasq -d -q --dhcp-range=192.168.1.3,192.168.1.254 --enable-tftp --tftp-root=/var/lib/tftpboot --dhcp-userclass=set:ipxe,iPXE --dhcp-boot=tag:#ipxe,undionly.kpxe --dhcp-boot=tag:ipxe,http://matchbox.foo:8080/boot.ipxe --address=/matchbox.foo/192.168.1.2 --log-queries --log-dhcp +sudo docker run --rm --cap-add=NET_ADMIN --net=host quay.io/coreos/dnsmasq \ + -d -q \ + --dhcp-range=192.168.1.1,proxy,255.255.255.0 \ + --enable-tftp --tftp-root=/var/lib/tftpboot \ + --dhcp-userclass=set:ipxe,iPXE \ + --pxe-service=tag:#ipxe,x86PC,"PXE chainload to iPXE",undionly.kpxe \ + --pxe-service=tag:ipxe,x86PC,"iPXE",http://matchbox.example.com:8080/boot.ipxe \ + --log-queries \ + --log-dhcp ``` -Ensure that `matchbox.foo` resolves to a `matchbox` deployment and that you've allowed the services to run in your firewall configuration. +Be sure to allow enabled services in your firewall configuration. ```sh $ sudo firewall-cmd --add-service=dhcp --add-service=tftp --add-service=dns ``` +## GRUB + +Grub can be used to delegate as well. + +`grub-mknetdir --net-directory=/var/lib/tftpboot` + +/var/lib/tftpboot/boot/grub/grub.cfg: +```ini +insmod i386-pc/http.mod +set root=http,matchbox.foo:8080 +configfile /grub +``` + +Make sure to replace variables in the example config files; instead of iPXE variables, use GRUB variables. Check the [GRUB2 manual](https://www.gnu.org/software/grub/manual/grub.html#Network). + ## Troubleshooting See [troubleshooting](troubleshooting.md). diff --git a/contrib/dnsmasq/CHANGES.md b/contrib/dnsmasq/CHANGES.md new file mode 100644 index 00000000..d4dbe1a6 --- /dev/null +++ b/contrib/dnsmasq/CHANGES.md @@ -0,0 +1,13 @@ +# dnsmasq + +Notable changes image releases. The dnsmasq project [upstream](http://www.thekelleys.org.uk/dnsmasq/doc.html) has its own [changelog](http://www.thekelleys.org.uk/dnsmasq/CHANGELOG). + +## v0.4.0 + +* `dnsmasq` package version 2.76 +* Rebuild with alpine:3.5 base image to receive patches +* Update CoreOS `grub.efi` to be recent (stable, 1298.7.0) + +## v0.3.0 + +* `dnsmasq` package version 2.75 diff --git a/contrib/dnsmasq/Makefile b/contrib/dnsmasq/Makefile index c0297011..e31a2247 100644 --- a/contrib/dnsmasq/Makefile +++ b/contrib/dnsmasq/Makefile @@ -12,8 +12,8 @@ undionly: .PHONY: docker-image docker-image: undionly - sudo docker build --rm=true -t $(IMAGE_REPO):$(VERSION) . - sudo docker tag $(IMAGE_REPO):$(VERSION) $(IMAGE_REPO):latest + @sudo docker build --rm=true -t $(IMAGE_REPO):$(VERSION) . + @sudo docker tag $(IMAGE_REPO):$(VERSION) $(IMAGE_REPO):latest .PHONY: docker-push docker-push: diff --git a/scripts/devnet b/scripts/devnet index d82cd016..d0601f2d 100755 --- a/scripts/devnet +++ b/scripts/devnet @@ -102,7 +102,7 @@ function create { --dns=host \ --mount volume=config,target=/etc/dnsmasq.conf \ --volume config,kind=host,source=$DIR/../contrib/dnsmasq/metal0.conf \ - quay.io/coreos/dnsmasq:v0.3.0 \ + quay.io/coreos/dnsmasq:v0.4.0 \ --caps-retain="CAP_NET_ADMIN,CAP_NET_BIND_SERVICE" status