1# hcsshim
2
3[](https://github.com/microsoft/hcsshim/actions?query=branch%3Amaster)
4
5This package contains the Golang interface for using the Windows [Host Compute Service](https://techcommunity.microsoft.com/t5/containers/introducing-the-host-compute-service-hcs/ba-p/382332) (HCS) to launch and manage [Windows Containers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/). It also contains other helpers and functions for managing Windows Containers such as the Golang interface for the Host Network Service (HNS), as well as code for the [guest agent](./internal/guest/README.md) (commonly referred to as the GCS or Guest Compute Service in the codebase) used to support running Linux Hyper-V containers.
6
7It is primarily used in the [Moby](https://github.com/moby/moby) and [Containerd](https://github.com/containerd/containerd) projects, but it can be freely used by other projects as well.
8
9## Building
10
11While this repository can be used as a library of sorts to call the HCS apis, there are a couple binaries built out of the repository as well. The main ones being the Linux guest agent, and an implementation of the [runtime v2 containerd shim api](https://github.com/containerd/containerd/blob/master/runtime/v2/README.md).
12### Linux Hyper-V Container Guest Agent
13
14To build the Linux guest agent itself all that's needed is to set your GOOS to "Linux" and build out of ./cmd/gcs.
15```powershell
16C:\> $env:GOOS="linux"
17C:\> go build .\cmd\gcs\
18```
19
20or on a Linux machine
21```sh
22> go build ./cmd/gcs
23```
24
25If you want it to be packaged inside of a rootfs to boot with alongside all of the other tools then you'll need to provide a rootfs that it can be packaged inside of. An easy way is to export the rootfs of a container.
26
27```sh
28docker pull busybox
29docker run --name base_image_container busybox
30docker export base_image_container | gzip > base.tar.gz
31BASE=./base.tar.gz
32make all
33```
34
35If the build is successful, in the `./out` folder you should see:
36```sh
37> ls ./out/
38delta.tar.gz initrd.img rootfs.tar.gz
39```
40
41### Containerd Shim
42For info on the Runtime V2 API: https://github.com/containerd/containerd/blob/master/runtime/v2/README.md.
43
44Contrary to the typical Linux architecture of shim -> runc, the runhcs shim is used both to launch and manage the lifetime of containers.
45
46```powershell
47C:\> $env:GOOS="windows"
48C:\> go build .\cmd\containerd-shim-runhcs-v1
49```
50
51Then place the binary in the same directory that Containerd is located at in your environment. A default Containerd configuration file can be generated by running:
52```powershell
53.\containerd.exe config default | Out-File "C:\Program Files\containerd\config.toml" -Encoding ascii
54```
55
56This config file will already have the shim set as the default runtime for cri interactions.
57
58To trial using the shim out with ctr.exe:
59```powershell
60C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/windows/nanoserver:2004 windows-test cmd /c "echo Hello World!"
61```
62
63## Contributing
64
65This project welcomes contributions and suggestions. Most contributions require you to agree to a
66Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
67the rights to use your contribution. For details, visit https://cla.microsoft.com.
68
69When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
70a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
71provided by the bot. You will only need to do this once across all repos using our CLA.
72
73We also require that contributors [sign their commits](https://git-scm.com/docs/git-commit) using `git commit -s` or `git commit --signoff` to
74certify they either authored the work themselves or otherwise have permission to use it in this project. Please see https://developercertificate.org/ for
75more info, as well as to make sure that you can attest to the rules listed. Our CI uses the [DCO Github app](https://github.com/apps/dco) to ensure
76that all commits in a given PR are signed-off.
77
78## Code of Conduct
79
80This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
81For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
82contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
83
84## Dependencies
85
86This project requires Golang 1.17 or newer to build.
87
88For system requirements to run this project, see the Microsoft docs on [Windows Container requirements](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/system-requirements).
89
90## Reporting Security Issues
91
92Security issues and bugs should be reported privately, via email, to the Microsoft Security
93Response Center (MSRC) at [secure@microsoft.com](mailto:secure@microsoft.com). You should
94receive a response within 24 hours. If for some reason you do not, please follow up via
95email to ensure we received your original message. Further information, including the
96[MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in
97the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).
98
99For additional details, see [Report a Computer Security Vulnerability](https://technet.microsoft.com/en-us/security/ff852094.aspx) on Technet
100
101---------------
102Copyright (c) 2018 Microsoft Corp. All rights reserved.
View as plain text