{"id":13582490,"url":"https://github.com/TheNewNormal/corectl","last_synced_at":"2025-04-06T14:31:02.173Z","repository":{"id":33664802,"uuid":"37317400","full_name":"TheNewNormal/corectl","owner":"TheNewNormal","description":"CoreOS over macOS made very simple","archived":false,"fork":false,"pushed_at":"2019-03-01T01:45:40.000Z","size":7022,"stargazers_count":287,"open_issues_count":26,"forks_count":21,"subscribers_count":10,"default_branch":"golang","last_synced_at":"2024-11-05T22:41:33.702Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheNewNormal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-12T11:02:22.000Z","updated_at":"2024-11-05T16:21:05.000Z","dependencies_parsed_at":"2022-09-13T08:20:37.571Z","dependency_job_id":null,"html_url":"https://github.com/TheNewNormal/corectl","commit_stats":null,"previous_names":["antoniomeireles/coreos-xhyve"],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheNewNormal%2Fcorectl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheNewNormal%2Fcorectl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheNewNormal%2Fcorectl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheNewNormal%2Fcorectl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheNewNormal","download_url":"https://codeload.github.com/TheNewNormal/corectl/tar.gz/refs/heads/golang","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247495768,"owners_count":20948105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:02:45.952Z","updated_at":"2025-04-06T14:30:58.996Z","avatar_url":"https://github.com/TheNewNormal.png","language":"Go","readme":"# CoreOS _over_ macOS made simple\n\n| read this first |\n| :----------- |\n|  - You **must** be running macOS Yosemite, 10.10.3, or later on a 2010, or later, Macintosh (i.e. one with a CPU that supports EPT) for everything to work. |\n|  - Starting with **0.7.18** the bundled `qcow-tool` helper has a _runtime_ dependency in `libev`. Until we sort out how to build it statically, you need to make it available in the local system - if you are using [homebrew](http://brew.sh) that is as easy as `brew install libev`.|\n|  - If you are still using **any** version of VirtualBox older than 4.3.30 then `corectl` will **crash** your system either if VirtualBox is running, or had been run previously after the last reboot (see **xhyve**'s issues [#5](https://github.com/mist64/xhyve/issues/5) and [#9](https://github.com/mist64/xhyve/issues/9) for the full context). So, if for some reason, you are unable to update VirtualBox to the latest, either of the 4.x or 5.x streams, and were using it in your current session please make sure to restart your Mac before attempting to run `corectl`. |\n|  - If you are using some sort of desktop firewall in your macOS host (ESET, Little Snitch, whatever) please make sure that it **allows traffic from/to the `bridge100` interface to the host** as otherwise no VM will ever able to succefully boot (as it can't fetch the ignition configs, etc from the host's running `corectld`)|\n\n\n# step by step instructions\n\n## install **corectl**\n\n### installing a release build (prefered for end users)\n\n#### via [homebrew](http://brew.sh)\n\n```\n❯❯❯ brew install corectl\n```\n\n#### downloading from GitHub\n\njust go to our **[releases](https://github.com/genevera/corectl/releases)**\npage and download the tarball with the binaries to your system, and then\nunpack its' contents placing them somewhere in some directory in your\n`${PATH}` (`/usr/local/bin/` is usually a good choice)\n\n### build it locally (for power users)\n\n  ```\n  ❯❯❯ mkdir -p ${GOPATH}/src/github.com/genevera/\n  ❯❯❯ cd ${GOPATH}/src/github.com/genevera/\n  ❯❯❯ git clone git@github.com:genevera/corectl.git\n  ❯❯❯ cd corectl\n  ❯❯❯ make\n  ```\n\n  \u003e the built binaries will _then_ appear inside\n  \u003e `${GOPATH}/src/github.com/genevera/corectl/bin`\n\n## **start the** corectl **server daemon** (**corectld**)\n\u003e this is a **required** step starting with **corectl**'s **0.7.0** release\n\n  ```\n  ❯❯❯ /usr/local/bin/corectld\n  ```\n\n## kickstart a CoreOS VM\n\u003e the following command will fetch the `latest` CoreOS Alpha image\n\u003e available, if not already available locally, verify its integrity, and then\n\u003eboot it.\n\n  ```\n  ❯❯❯ corectl run\n  ```\n\nIn your terminal you will shortly see something like the following...\n\n  ```\n  ❯❯❯  corectl run\n  ---\u003e 'B4AF19D1-DDEE-4A16-8058-1A7C3579F203' started successfully with address 192.168.64.210 and PID 76202\n  ---\u003e 'B4AF19D1-DDEE-4A16-8058-1A7C3579F203' boot logs can be found at '/Users/am/.coreos/running/B4AF19D1-DDEE-4A16-8058-1A7C3579F203/log'\n  ---\u003e 'B4AF19D1-DDEE-4A16-8058-1A7C3579F203' console can be found at '/Users/am/.coreos/running/B4AF19D1-DDEE-4A16-8058-1A7C3579F203/tty'\n```\n\nAccessing the newly created CoreOS instance is just a few more clicks away...\n  ```\n  ❯❯❯  corectl ssh B4AF19D1-DDEE-4A16-8058-1A7C3579F203\n  ```\n\n## usage _(straight from the online help)_\n### **corectld**\n  ```\n  CoreOS over macOS made simple. \u003chttp://github.com/genevera/corectl\u003e\n  Copyright (c) 2015-2016, António Meireles\n\n  Usage:\n      corectld [flags]\n      corectld [command]\n\n  Available Commands:\n      start       Starts corectld\n      status      Shows corectld status\n      stop        Stops corectld\n      version     Shows version information\n\n  Flags:\n    -d, --debug   adds additional verbosity, and options, directed at debugging purposes and power users\n\n  Use \"corectld [command] --help\" for more information about a command.\n\n  All flags can also be set via upper-case environment variables prefixed with \"COREOS_\"\n  For example, \"--debug\" =\u003e \"COREOS_DEBUG\"\n  ```\n### **corectl**\n  ```\n  CoreOS over macOS made simple. \u003chttp://github.com/genevera/corectl\u003e\n  Copyright (c) 2015-2016, António Meireles\n\n  Usage:\n      corectl [flags]\n      corectl [command]\n\n  Available Commands:\n      kill        Halts one or more running CoreOS instances\n      load        Loads CoreOS instances defined in an instrumentation file.\n      ls          Lists the CoreOS images available locally\n      ps          Lists running CoreOS instances\n      pull        Pulls a CoreOS image from upstream\n      put         copy file to inside VM\n      query       Display information about the running CoreOS instances\n      rm          Remove(s) CoreOS image(s) from the local filesystem\n      run         Boots a new CoreOS instance\n      ssh         Attach to or run commands inside a running CoreOS instance\n      version     Shows version information\n\n  Flags:\n    -d, --debug   adds additional verbosity, and options, directed at debugging purposes and power users\n\n  Use \"corectl [command] --help\" for more information about a command.\n\n  All flags can also be set via upper-case environment variables prefixed with \"COREOS_\"\n  For example, \"--debug\" =\u003e \"COREOS_DEBUG\"\n  ```\n\n  \u003e [here](documentation/markdown/corectl.md) you can find the full\n  \u003e auto-generated documentation.\n\n## simple usage recipe: a **docker** and **rkt** playground\n\n### create a volume to store your persistent data\n  \u003e [`qcow-tool`](https://github.com/mirage/ocaml-qcow), that we use below, is\n  \u003e shipped together with **corectl** and creates qcow2 images.\n  \u003e\n  \u003e Please do note that the `--size` argument\n  \u003e **must** to be suffixed the _right_ way - `KiB`/`MiB`/`GiB`/`TiB`/`PiB`\n\n  ```\n  ❯❯❯ qcow-tool create --size=16GiB var_lib_docker.img.qcow2\n  ```\n  \u003e will become `/var/lib/{docker|rkt}`. In this example case we created a\n  \u003e **QCow2** volume with 16GB.\n\n| a quick note regarding Raw volumes |\n| :--------- |\n| **Raw** volumes were the default until version **[0.7.12](https://github.com/genevera/corectl/releases/tag/v0.7.12)**. \u003cbr\u003e They are still supported but become a deprecated feature that may disappear some point in the future. |\n\n### *format* and label it\n  \u003e we'll format and label the newly created volume from within a transient VM\n  \u003e as it's the simplest way. We're formatting it with `ext4` but you can choose\n  \u003e any filesystem you like assuming it is a CoreOS supported one.\n\n  ```\n  ❯❯❯ corectl run  --name foo --volume=var_lib_docker.img.qcow2\n  ❯❯❯ corectl ssh foo \"sudo mke2fs -b 1024 -i 1024 -t ext4 -m0 /dev/vda \u0026\u0026 \\\n        sudo e2label /dev/vda rkthdd \"\n  ❯❯❯ corectl halt foo\n  ```\n\n  above, we labeled our volume `rkthdd` which is the *signature* that our\n  [*recipe*](examples/cloud-init/docker-only-with-persistent-storage.txt) expects.\n\n  \u003eby relying in *labels* for volume identification we get around the issues we'd\n  \u003ehave otherwise if we were depending on the actual volume name (/dev/vd...) as\n  \u003ethose would have to be hardcoded (an issue, if one is mix and matching\n  \u003emultiple recipes all dealing with different volumes...)\n\n### start your **docker** and **rkt** playground.\n  ```\n  ❯❯❯ UUID=deadbeef-dead-dead-dead-deaddeafbeef \\\n    corectl run --volume absolute_or_relative_path/to/persistent.img \\\n    --cloud_config examples/cloud-init/docker-only-with-persistent-storage.txt \\\n    --cpus 2 --memory 2048 --name containerland\n  ```\n this will start a VM named `containerland` with the\n volume we created previously attached, 2 virtual cores and 2GB of RAM. The\n provided [cloud-config](examples/cloud-init/docker-only-with-persistent-storage.txt)\n will format the given volume (if it wasn't yet) and bind mount both\n `/var/lib/rkt` and `/var/lib/docker` on top of it. Docker will also become\n available through socket activation.\n\n \u003e above we passed arguments to the VM both via environment variables and\n \u003e command flags. both ways are fully supported, just use whatever suits your\n \u003e needs better.\n\n### now...\n\n  ```\n  ❯❯❯ corectl ps\n  Server:\n    Version:      0.7.0\n    Go Version:   go1.6.2\n    Built:        Mon Jul 04 10:05:51 WEST 2016\n    OS/Arch:      darwin/amd64\n\n    Pid:          76155\n    Uptime:       37 minutes ago\n\n  Activity:\n  Active VMs:     1\n  Total Memory:   2048\n  Total vCores:   2\n\n  UUID:           A163767A-78DC-41F9-AA66-E57B6C6CAB1A\n    Name:         containerland\n    Version:      1097.0.0\n    Channel:      alpha\n    vCPUs:        3\n    Memory (MB):  2048\n    Pid:          76807\n    Uptime:       25 minutes ago\n    Sees World:   true\n    cloud-config: /Users/am/code/corectl/src/github.com/genevera/corectl/examples/cloud-init/docker-only-with-persistent-storage.txt\n    Network:\n      eth0:       192.168.64.2\n    Volumes:\n    /dev/vda      /Users/am/code/corectl/persistentData/var_lib_docker.img\n  ```\n\n  ```\n  ❯❯❯ docker -H $(corectl q containerland --ip):2375 images -a\n  REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE\n  centos              latest              05188b417f30        2 days ago          196.8 MB\n  busybox             latest              2b8fd9751c4c        10 days ago         1.093 MB\n  fedora              latest              f9873d530588        13 days ago         204.4 MB\n  ```\n\nor ...\n\n  ```\n    ❯❯❯ corectl ssh containerland\n    CoreOS stable (1097.0.0)\n    Last login: Mon Jul  4 09:17:26 2016 from 192.168.64.1\n    Update Strategy: No Reboots\n  ```\nor ...\n  ```\n  ❯❯❯ corectl ssh containerland \"sudo rkt list\"\n  UUID\tAPP\tIMAGE NAME\tSTATE\tCREATED\tSTARTED\tNETWORKS\n  ```\n\n\u003e All running VMs become reachable by name transparently on the host using\n\u003e  macOS' native name resolution machinery\n\u003e  ```\n\u003e  ❯❯❯ ping -c 1 containerland\n\u003e  PING containerland.coreos.local (192.168.64.2): 56 data bytes\n\u003e  64 bytes from 192.168.64.2: icmp_seq=0 ttl=64 time=0.239 ms\n\u003e\n\u003e  --- containerland.coreos.local ping statistics ---\n\u003e  1 packets transmitted, 1 packets received, 0.0% packet loss\n\u003e  round-trip min/avg/max/stddev = 0.239/0.239/0.239/0.000 ms\n\u003e  ```\n\n### have fun!\n\n## Tracing\n\nThanks to [hyperkit](https://github.com/docker/hyperkit) (that we consume as\n`corectld.runner`) there are available a  number of static DTrace probes to\nsimplify investigation of performance problems. To list the probes supported by\nyour version of corectl, type the following command while `corectld` is running:\n\n `$ sudo dtrace -l -P 'hyperkit$target' -p $(pgrep corectld.runner)`\n\nRefer to scripts in `examples/dtrace/` directory for examples of possible usage\nand available probes.\n\n# projects using **corectl**\n\n- [Rimas Mocevicius](https://github.com/rimusz) entire toolset of macOS GUI apps\nis now using **corectl** underneath, and has become part of the\n[genevera](http://github.com/genevera) project\n  - **[Corectl.app controlling app of corectld server daemon](https://github.com/genevera/corectl.app)**\n  - **[CoreOS VM for macOS](https://github.com/genevera/coreos-osx)**\n  - **[Kubernetes Solo Cluster for macOS](https://github.com/genevera/kube-solo-osx)**\n  - **[Multi node Kubernetes Cluster for macOS](https://github.com/genevera/kube-cluster-osx)**\n\n# acknowledgements\n\n-  [Michael Steil](https://github.com/mist64) for releasing into the wild his\n   awesome [xhyve](https://github.com/mist64/xhyve) lightweight macOS\n   virtualization solution\n-  [Docker Inc](http://www.docker.com/) for keep improving it through\n   [hyperkit](https://github.com/docker/hyperkit).\n-  [Brandon Philips](https://github.com/philips), from\n   [CoreOS](http://www.coreos.com), who come with the original, **bash** based,\n   [coreos-xhyve](https://github.com/coreos/coreos-xhyve) prototype that this\n   project supersedes\n\n# contributing\n\n**corectl** is an [open source](http://opensource.org/osd) project released under\nthe [Apache License, Version 2.0](http://opensource.org/licenses/Apache-2.0),\ncontributions and sugestions are gladly welcomed!\n","funding_links":[],"categories":["Go","📦 Legacy \u0026 Inactive Projects"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheNewNormal%2Fcorectl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheNewNormal%2Fcorectl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheNewNormal%2Fcorectl/lists"}