github-personal/matchbox
1
0
Fork 0
mirror of https://github.com/outbackdingo/matchbox.git synced 2026-01-27 10:19:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #487 from coreos/dnsmasq-docs-fixes

Browse Source 
Update docs, changelog, and scripts for dnsmasq:v0.4.0
This commit is contained in:
Dalton Hubble
2017-04-19 14:53:32 -07:00
committed by GitHub
parent fa31b0a58c 45bece3cf7
commit 7dfb04c4af
6 changed files with 126 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
Documentation/getting-started-rkt.md
View File

@@ -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.

20
Documentation/grub.md
View File

@@ -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

114
Documentation/network-setup.md
View File

@@ -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).

13
contrib/dnsmasq/CHANGES.md Normal file
View File

@@ -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

4
contrib/dnsmasq/Makefile
View File

@@ -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:

2
scripts/devnet
View File

@@ -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