Skip to content

Commit fcde327

Browse files
zcheezchee
committed
README: update available flags and more readable
Signed-off-by: Koichi Shiraishi <zchee.io@gmail.com>
1 parent 3c50c56 commit fcde327

File tree

1 file changed

+177
-102
lines changed

1 file changed

+177
-102
lines changed

‎README.md‎

Lines changed: 177 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,115 +1,222 @@
1-
# docker-machine-driver-xhyve
1+
docker-machine-driver-xhyve
2+
===========================
23

3-
| Travis-CI | CircleCI |
4-
|:---------:|:---------:|
5-
| [![Build Status](https://travis-ci.org/zchee/docker-machine-driver-xhyve.svg?branch=master)](https://travis-ci.org/zchee/docker-machine-driver-xhyve) | [![Circle CI](https://circleci.com/gh/zchee/docker-machine-driver-xhyve/tree/master.svg?style=svg)](https://circleci.com/gh/zchee/docker-machine-driver-xhyve/tree/master) |
4+
| Releases | Travis-CI | CircleCI |
5+
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
6+
| [![Releases](https://img.shields.io/github/release/zchee/docker-machine-driver-xhyve.svg?style=flat)](https://github.com/zchee/docker-machine-driver-xhyve/releases) | [![Build Status](https://travis-ci.org/zchee/docker-machine-driver-xhyve.svg?branch=master)](https://travis-ci.org/zchee/docker-machine-driver-xhyve) | [![Circle CI](https://circleci.com/gh/zchee/docker-machine-driver-xhyve/tree/master.svg?style=svg)](https://circleci.com/gh/zchee/docker-machine-driver-xhyve/tree/master) |
67

7-
Docker Machine driver plugin for [xhyve](https://github.com/mist64/xhyve) native OS X Hypervisor
8+
libmachine driver plugin for [xhyve](https://github.com/mist64/xhyve) native OS X Hypervisor
89

9-
Master branch inherited from [nathanleclaire/docker-machine-driver-xhyve](https://github.com/nathanleclaire/docker-machine-driver-xhyve). Thanks [@nathanleclaire](https://github.com/nathanleclaire) :)
10+
Master branch inherited from [nathanleclaire/docker-machine-xhyve](https://github.com/nathanleclaire/docker-machine-xhyve). Thanks [@nathanleclaire](https://github.com/nathanleclaire) :)
1011
If you have issues or pull-requests, Desired to be posted to this repository.
1112

13+
Screencast
14+
----------
1215

13-
## Screencast
14-
[![asciicast](imgs/launch.png)](https://asciinema.org/a/29930)
16+
[![asciinema](imgs/launch.png)](https://asciinema.org/a/29930)
1517

18+
Requirements
19+
------------
1620

17-
## Required
21+
### docker-machine or minikube
1822

19-
### Other than Mac OS X 10.11.4 build (15E27e)
20-
Mac OS X 10.11.4 (15E27e) has a **Hypervisor.framework bug**.
21-
This is Apple's bug.
22-
but, Apple has been fixed build 15E33e. Please upgrade latest beta.
23-
See
24-
- https://asciinema.org/a/34798 (15E27e)
25-
- https://asciinema.org/a/34797 (15E33e)
23+
- https://github.com/docker/machine
24+
- https://github.com/kubernetes/minikube
2625

27-
If you launch the `docker-machine-driver-xhyve` on build 15E27e, will displayed
26+
docker-machine-driver-xhyve using libmachine plugin model.
2827

29-
```bash
30-
open : no such file or directory
31-
```
28+
**Please do not post the issue of this repository to the docker/machine and kubernetes/minikube**
29+
It will interfere with the development of the docker-machine or minikube.
30+
If you were doubt problem either, please post to this repository [issues](https://github.com/zchee/docker-machine-driver-xhyve/issues).
3231

33-
on "Convert UUID to MAC address...".
34-
and, In original `xhyve`,
32+
- docker-machine
3533

36-
```bash
37-
hv_vm_create failed
38-
```
34+
- See https://github.com/docker/machine/releases
3935

40-
### docker-machine
41-
https://github.com/docker/machine
36+
- minikube
4237

43-
docker-machine-driver-xhyve using docker-machine plugin model.
38+
- See https://github.com/kubernetes/minikube/releases
4439

45-
**Please do not post the issue of this repository to the docker/machine**
46-
It will interfere with the development of the docker-machine.
47-
If you were doubt problem either, please post to this repository [issues](https://github.com/zchee/docker-machine-driver-xhyve/issues).
40+
Install
41+
-------
4842

49-
```bash
50-
> go get github.com/docker/machine
51-
> cd $GOPATH/src/github.com/docker/machine
52-
# Build docker-machine binary
53-
> make build
54-
# Install docker-machine binary into /usr/local/bin/
55-
> make install
56-
```
43+
Use [Homebrew/brew](https://github.com/Homebrew/brew):
5744

58-
## Install
59-
60-
Use [Homebrew/homebrew](https://github.com/Homebrew/homebrew),
61-
62-
```bash
45+
```sh
6346
$ brew install docker-machine-driver-xhyve
6447

6548
# docker-machine-driver-xhyve need root owner and uid
6649
$ sudo chown root:wheel $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve
6750
$ sudo chmod u+s $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve
6851
```
6952

70-
Use `go get`,
53+
Use `go` with `make`:
54+
If you want to support qcow2 disk image format, need install [mirage/ocaml-qcow](https://github.com/mirage/ocaml-qcow). See [docker/hyperkit#building](https://github.com/docker/hyperkit#building).
7155

72-
```bash
56+
```sh
7357
# Need Go 1.5 vendoring support
7458
$ export GO15VENDOREXPERIMENT=1
7559

76-
$ go get -u github.com/zchee/docker-machine-driver-xhyve
60+
$ go get -u -d github.com/zchee/docker-machine-driver-xhyve
61+
$ cd $GOPATH/src/github.com/zchee/docker-machine-driver-xhyve
62+
63+
# Install qcow-format for qcow2 disk image format
64+
$ brew install opam libev
65+
$ opam init
66+
$ eval `opam config env`
67+
$ opam install uri qcow-format conf-libev
68+
69+
# Install docker-machine-driver-xhyve binary into /usr/local/bin
70+
$ make install
7771

7872
# docker-machine-driver-xhyve need root owner and uid
79-
$ sudo chown root:wheel $GOPATH/bin/docker-machine-driver-xhyve
80-
$ sudo chmod u+s $GOPATH/bin/docker-machine-driver-xhyve
73+
$ sudo chown root:wheel /usr/local/bin/docker-machine-driver-xhyve
74+
$ sudo chmod u+s /usr/local/bin/docker-machine-driver-xhyve
8175
```
8276

83-
## Usage
77+
Usage
78+
-----
8479

8580
### Available flags
8681

87-
| Flag name | Environment variable | Type | Description | Default |
88-
|----------------------------------|--------------------------------|--------|------------------------------------------|----------------------------------------------------------|
89-
| `--xhyve-boot2docker-url` | `XHYVE_BOOT2DOCKER_URL` | string | The URL(Path) of the boot2docker image | `$HOME/.docker/machine/cache/boot2docker.iso` |
90-
| `--xhyve-cpu-count` | `XHYVE_CPU_COUNT` | int | Number of CPUs to use the create the VM | `1` |
91-
| `--xhyve-memory-size` | `XHYVE_MEMORY_SIZE` | int | Size of memory for the guest | `1024` |
92-
| `--xhyve-disk-size` | `XHYVE_DISK_SIZE` | int | Size of disk for the guest (MB) | `20000` |
93-
| `--xhyve-boot-cmd` | `XHYVE_BOOT_CMD` | string | Booting xhyve iPXE commands | See [boot2docker/boot2docker/doc/AUTOMATED_SCRIPT.md][1] |
94-
| `--xhyve-virtio-9p` | `XHYVE_VIRTIO_9P` | bool | Enable `virtio-9p` folder share | `false` |
95-
| `--xhyve-experimental-nfs-share` | `XHYVE_EXPERIMENTAL_NFS_SHARE` | bool | Enable `NFS` folder share (experimental) | `false` |
82+
| Flag name | Environment variable | Type | Default |
83+
|----------------------------------|--------------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------|
84+
| `--xhyve-boot2docker-url` | `XHYVE_BOOT2DOCKER_URL` | string | `$HOME/.docker/machine/cache/boot2docker.iso` |
85+
| `--xhyve-cpu-count` | `XHYVE_CPU_COUNT` | int | `1` |
86+
| `--xhyve-memory-size` | `XHYVE_MEMORY_SIZE` | int | `1024` |
87+
| `--xhyve-disk-size` | `XHYVE_DISK_SIZE` | int | `20000` |
88+
| `--xhyve-uuid` | `XHYVE_UUID` | int | `''` |
89+
| `--xhyve-boot-cmd` | `XHYVE_BOOT_CMD` | string | See [AUTOMATED_SCRIPT.md](https://github.com/boot2docker/boot2docker/blob/master/doc/AUTOMATED_SCRIPT.md#extracting-boot-parameters) |
90+
| `--xhyve-boot-kernel` | `XHYVE_BOOT_KERNEL` | string | `''` |
91+
| `--xhyve-boot-initrd` | `XHYVE_BOOT_INITRD` | string | `''` |
92+
| `--xhyve-qcow2` | `XHYVE_QCOW2` | bool | `false` |
93+
| `--xhyve-virtio-9p` | `XHYVE_VIRTIO_9P` | bool | `false` |
94+
| `--xhyve-experimental-nfs-share` | `XHYVE_EXPERIMENTAL_NFS_SHARE` | bool | `false` |
95+
96+
#### `--xhyve-boot2docker-url`
97+
98+
The URL(Path) of the boot2docker image.
99+
By default, use cached iso file path.
100+
101+
#### `--xhyve-cpu-count`
102+
103+
Number of CPUs to use the create the VM.
104+
If set `-1`, use logical CPUs usable by the current process.
105+
106+
#### `--xhyve-memory-size`
107+
108+
Size of memory for the guest.
109+
110+
#### `--xhyve-disk-size`
111+
112+
Size of disk for the guest (MB).
113+
114+
#### `--xhyve-uuid`
115+
116+
The UUID for the machine.
117+
By default, generate and use ramdom UUID. See [xhyve/uuid.go](https://github.com/zchee/docker-machine-driver-xhyve/blob/master/xhyve/uuid.go)
118+
119+
#### `--xhyve-boot-cmd`
120+
121+
Booting xhyve kexec commands.
122+
By default, use
123+
`loglevel=3 user=docker console=ttyS0 console=tty0 noembed nomodeset norestore waitusb=10 base host=boot2docker`
124+
125+
#### `--xhyve-boot-kernel`
126+
127+
Booting kernel file path.
128+
By default, will automatically parses the file path using `(vmlinu[xz]|bzImage)[\d]*`.
129+
130+
#### `--xhyve-boot-initrd`
131+
132+
Booting initrd file path.
133+
By default, will automatically parses the `initrd` contains file path.
134+
135+
#### `--xhyve-qcow2`
136+
137+
Use `qcow2` disk format.
138+
If you using minikube, `CONFIG_VIRTIO_BLK=y` support is included in minikube-iso as of version v0.0.6.
139+
140+
#### `--xhyve-virtio-9p`
141+
142+
Enable `virtio-9p` folder share.
143+
If you using docker-machine, `CONFIG_NET_9P=y` support is included in boot2docker as of version v1.10.2.
144+
145+
#### `--xhyve-experimental-nfs-share`
146+
147+
Enable `NFS` folder sharing.
148+
149+
Known isuue
150+
-----------
151+
152+
### Does not clean up the vmnet when remove a VM
153+
154+
Currently, `docker-machine-driver-xhyve` does not clean up the `dhcpd_leases`.
155+
like,
96156

97-
`virtio-9p` support is included in boot2docker as of version 1.10.2. For earlier releases you need a custom `boot2docker.iso`
98-
See https://github.com/zchee/boot2docker-legacy/releases.
157+
```sh
158+
# Running xhyve vm. for example, assign 192.168.64.1
159+
$ docker-machine create --driver xhyve xhyve-test
160+
|
161+
# Send ACPI signal(poweroff) signal over the ssh
162+
$ docker-machine rm xhyve-test
163+
|
164+
# Re-create xhyve vm, will assign 192.168.64.2
165+
docker-machine create --driver xhyve xhyve-test
166+
```
167+
168+
It will assigned to 192.168.64.**2**. If create another vm, assigned to 192.168.64.**3**.
169+
But 192.168.64.**1** are not using anyone.
170+
171+
`vmnet.framework` seems to have decide the IP based on below files
172+
173+
- `/var/db/dhcpd_leases`
174+
- `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist`
175+
176+
So, If you want to reset IP database, please remove it manually. but **very risky**.
177+
Note that `vmnet.framework` shared net address range is `192.168.64.1` ~ `192.168.64.255`. You can make 255 vm.
178+
179+
I will implement the clean-up process after understanding the `vmnet.framework`.
180+
181+
### Can't launch on macOS 10.11.4 build 15E27e
182+
183+
Mac OS X 10.11.4 build `15E27e` has a **Hypervisor.framework bug**.
184+
This is Apple's bug.
185+
But, Apple has been fixed build `15E33e`.
186+
187+
If you launch the `docker-machine-driver-xhyve` on build 15E27e, will displayed
188+
189+
```sh
190+
open : no such file or directory
191+
```
192+
193+
and, In original `xhyve`,
194+
195+
```sh
196+
hv_vm_create failed
197+
```
198+
199+
See
200+
201+
- https://asciinema.org/a/34798 (15E27e)
202+
- https://asciinema.org/a/34797 (15E33e)
203+
204+
Could you report?
205+
-----------------
99206

100-
## Would you do me a favor?
101207
I'm very anxious whether other users(except me) are able to launch the xhyve.
102-
So, if you were able to launch the xhyve use docker-machine-driver-xhyve, Would you post a report to this issue thread?
208+
So, if you were able to launch the xhyve use docker-machine-driver-xhyve, Could you post a report to this issue thread?
103209
https://github.com/zchee/docker-machine-driver-xhyve/issues/18
104210

105-
If OS X launched by the `Vagrant`, can be build, but will not be able to launch the Hypervisor.
211+
If macOS launched by the `Vagrant`, can be build, but will not be able to launch the Hypervisor.
106212
The cause probably because backend vm (Virtualbox, VMWare, parallels...) to hide the CPU infomation.
107213

108214
In the case of VMWare,
109-
```bash
215+
216+
```sh
110217
$ system_profiler SPHardwareDataType
111-
2015-11-21 10:04:18.972 system_profiler[458:1817] platformPluginDictionary: Can't get X86PlatformPlugin, return value 0
112-
2015-11-21 10:04:18.974 system_profiler[458:1817] platformPluginDictionary: Can't get X86PlatformPlugin, return value 0
218+
system_profiler[458:1817] platformPluginDictionary: Can't get X86PlatformPlugin, return value 0
219+
system_profiler[458:1817] platformPluginDictionary: Can't get X86PlatformPlugin, return value 0
113220
Hardware:
114221

115222
Hardware Overview:
@@ -128,41 +235,9 @@ Hardware:
128235
Serial Number (system): ************
129236
Hardware UUID: ********-****-****-****-************
130237

131-
> git clone https://github.com/mist64/xhyve && cd xhyve
132-
> make
133-
> ./xhyverun.sh
238+
$ git clone https://github.com/mist64/xhyve && cd xhyve
239+
$ make
240+
$ ./xhyverun.sh
134241
vmx_init: processor not supported by Hypervisor.framework
135242
Unable to create VM (-85377018)
136243
```
137-
138-
139-
## Known isuue
140-
141-
### Experimental shared folders
142-
`docker-machine-driver-xhyve` can create a `NFS` share automatically for you, but this feature
143-
is highly experimental. To use it specify `--xhyve-experimental-nfs-share` when creating your
144-
machine.
145-
146-
### Does not clean up the vmnet when remove a VM
147-
Current state, `docker-machine-driver-xhyve` does not clean up the vmnet configuration.
148-
149-
```
150-
Running xhyve vm (e.g. IP: 192.168.64.1)
151-
|
152-
`docker-machine rm`, ACPI signal(poweroff) in over ssh
153-
|
154-
vm is poweroff, `goxhyve` also killed with to poweroff
155-
|
156-
Re-create xhyve vm.
157-
```
158-
New vm's ip, It will probably be assigned to 192.168.64.**2**. If create another new vm, assigned to 192.168.64.**3**
159-
but 192.168.64.**1** are not using anyone.
160-
161-
`vmnet.framework` seems to have decided to IP based on `/var/db/dhcpd_leases` and `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist`
162-
So, To remove it manually, or Don’t even bother.
163-
Maybe `vmnet.framework` shared net address range `192.168.64.1` ~ `192.168.64.255`. You can make 255 vm.
164-
165-
I will fix after I understand the `vmnet.framework`
166-
167-
168-
[1]: https://github.com/boot2docker/boot2docker/blob/master/doc/AUTOMATED_SCRIPT.md#extracting-boot-parameters

0 commit comments

Comments
 (0)