HvSocket support for containers (#2353)

* HvSocket support for containers

Applications connecting from the host into the container should use
container-specific VMID. This ID will need to be the same as the
container's VMID inside the guest, which is calculated by HCS/GCS
like it's done in this PR by `HCSIDToGUID`.

To allow the container ID to work with HvSocket on the host, we
need to set up an AddressInfo mapping to tell HvSocket to redirect
the call into the UVM, which is done in this PR by default for
all WCOW containers.

Add internal `hvsocketaddr.exe` tool that clients can use to generate
VM ID for container.

Add a generic function for creating HvSocket address info mapping.

export a function that creates a mapping for containers only.

---------

Signed-off-by: Maksim An <[email protected]>
Co-authored-by: Kevin Parsons <[email protected]>

Author: anmaxvl

.github/workflows/ci.yml

@@ -657,6 +657,8 @@ jobs:
         name: Build uvmboot.exe
       - run: ${{ env.GO_BUILD_CMD }} ./internal/tools/zapdir
         name: Build zapdir.exe
+      - run: ${{ env.GO_BUILD_CMD }} ./internal/tools/hvsocketaddr
+        name: Build hvsocketaddr.exe
 
       - uses: actions/upload-artifact@v4
         if: ${{ github.event_name == 'pull_request' }}
@@ -669,6 +671,7 @@ jobs:
             wclayer.exe
             device-util.exe
             ncproxy.exe
+            hvsocketaddr.exe
             grantvmgroupaccess.exe
             networkagent.exe
             securitypolicy.exe

internal/hcs/schema2/properties.go

@@ -26,6 +26,8 @@ type Properties struct {
 
 	RuntimeId string `json:"RuntimeId,omitempty"`
 
+	SystemGUID string `json:"SystemGUID,omitempty"`
+
 	RuntimeTemplateId string `json:"RuntimeTemplateId,omitempty"`
 
 	State string `json:"State,omitempty"`

internal/hcs/schema2/property_type.go

@@ -23,4 +23,5 @@ const (
 	PTICHeartbeatStatus           PropertyType = "ICHeartbeatStatus"
 	PTProcessorTopology           PropertyType = "ProcessorTopology"
 	PTCPUGroup                    PropertyType = "CpuGroup"
+	PTSystemGUID                  PropertyType = "SystemGUID"
 )

internal/hcsoci/create.go

@@ -12,18 +12,20 @@ import (
 	"strconv"
 
 	"github.com/Microsoft/go-winio/pkg/guid"
+	specs "github.com/opencontainers/runtime-spec/specs-go"
+	"github.com/sirupsen/logrus"
+
 	"github.com/Microsoft/hcsshim/internal/cow"
 	"github.com/Microsoft/hcsshim/internal/guestpath"
 	"github.com/Microsoft/hcsshim/internal/hcs"
 	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/hvsocket"
 	"github.com/Microsoft/hcsshim/internal/layers"
 	"github.com/Microsoft/hcsshim/internal/log"
 	"github.com/Microsoft/hcsshim/internal/oci"
 	"github.com/Microsoft/hcsshim/internal/resources"
 	"github.com/Microsoft/hcsshim/internal/schemaversion"
 	"github.com/Microsoft/hcsshim/internal/uvm"
-	specs "github.com/opencontainers/runtime-spec/specs-go"
-	"github.com/sirupsen/logrus"
 )
 
 var (
@@ -278,6 +280,24 @@ func CreateContainer(ctx context.Context, createOptions *CreateOptions) (_ cow.C
 		if err != nil {
 			return nil, r, err
 		}
+
+		if coi.HostingSystem.OS() == "windows" {
+			log.G(ctx).Debug("redirecting container HvSocket for WCOW")
+			props, err := c.PropertiesV2(ctx, hcsschema.PTSystemGUID)
+			if err != nil {
+				return nil, r, fmt.Errorf("query created container properties failed: %w", err)
+			}
+			containerSystemGUID, err := guid.FromString(props.SystemGUID)
+			if err != nil {
+				return nil, r, fmt.Errorf("convert to system GUID failed: %w", err)
+			}
+			addressInfoCloser, err := hvsocket.CreateContainerAddressInfo(containerSystemGUID, coi.HostingSystem.RuntimeID())
+			if err != nil {
+				return nil, r, fmt.Errorf("redirect container HvSocket failed: %w", err)
+			}
+			r.Add(addressInfoCloser)
+		}
+
 		return c, r, nil
 	}
 

internal/hvsocket/hvsocket.go

@@ -0,0 +1,99 @@
+//go:build windows
+// +build windows
+
+package hvsocket
+
+import (
+	"context"
+	"fmt"
+	"unsafe"
+
+	"github.com/Microsoft/go-winio/pkg/guid"
+	"golang.org/x/sys/windows"
+
+	"github.com/Microsoft/hcsshim/internal/resources"
+)
+
+const (
+	addressFlagPassthru            = 0x00000001
+	ioCtlHVSocketUpdateAddressInfo = 0x21c004
+)
+
+type addressInfo struct {
+	systemID         guid.GUID
+	virtualMachineID guid.GUID
+	siloID           guid.GUID
+	flags            uint32
+}
+
+type addressInfoCloser struct {
+	handle windows.Handle
+}
+
+var _ resources.ResourceCloser = addressInfoCloser{}
+
+func (aic addressInfoCloser) Release(_ context.Context) error {
+	return windows.CloseHandle(aic.handle)
+}
+
+// CreateContainerAddressInfo creates an address info entry in HvSocket to redirect
+// the calls to the container silo inside UVM.
+func CreateContainerAddressInfo(containerID, uvmID guid.GUID) (resources.ResourceCloser, error) {
+	return CreateAddressInfo(containerID, uvmID, guid.GUID{}, true)
+}
+
+// CreateAddressInfo creates an address info entry in the HvSocket provider to map a
+// compute system GUID to a virtual machine ID or compartment ID.
+//
+// `systemID` is the compute system GUID to map.
+// `vmID` is the virtual machine ID to which the system GUID maps to. Must be guid.GUID{} to specify
+// that the system GUID maps to a network compartment ID on the hosting system.
+// `siloID` is the silo object ID to which the system GUID maps to.
+// `passthru` when vmID is not guid.GUID{}, specifies whether the systemID maps to the primary
+// compartment of the virtual machine (set to `false`) or to another compartment within the
+// virtual machine (set to `true`)
+func CreateAddressInfo(systemID, vmID, siloID guid.GUID, passthru bool) (resources.ResourceCloser, error) {
+	path := fmt.Sprintf(`\\.\HvSocketSystem\AddressInfo\{%s}`, systemID)
+	u16, err := windows.UTF16PtrFromString(path)
+	if err != nil {
+		return nil, err
+	}
+	h, err := windows.CreateFile(
+		u16,
+		windows.GENERIC_READ|windows.GENERIC_WRITE,
+		0,
+		nil,
+		windows.CREATE_NEW,
+		0,
+		0,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	addrInfo := addressInfo{
+		systemID:         systemID,
+		virtualMachineID: vmID,
+		siloID:           siloID,
+	}
+
+	if passthru {
+		addrInfo.flags |= addressFlagPassthru
+	}
+
+	var ret uint32
+	if err := windows.DeviceIoControl(
+		h,
+		ioCtlHVSocketUpdateAddressInfo,
+		(*byte)(unsafe.Pointer(&addrInfo)),
+		uint32(unsafe.Sizeof(addrInfo)),
+		nil,
+		0,
+		&ret,
+		nil,
+	); err != nil {
+		return nil, err
+	}
+
+	return &addressInfoCloser{h}, nil
+}

internal/tools/hvsocketaddr/README.md

@@ -0,0 +1,24 @@
+## Overview
+Applications connecting from the host into the container should use container-specific VMID.
+This VMID will need to be the same as the container's VMID inside the guest. One way to get
+the VMID is to query HCS for it or use this binary, which outputs the same VMID, when
+querying HCS isn't an option.
+
+## Build
+Build the binary as following
+```powershell
+> go build ./internal/tools/hvsocketaddr
+```
+
+## Run
+Find container ID using (e.g.) `crictl.exe`:
+```powershell
+> crictl ps --no-trunc
+```
+Note that we need full container ID, rather than a truncated one.
+
+Get VMID:
+```powershell
+> .\hvsocketaddr.exe <container-id>
+```
+The output VMID can be used by the services on the host.

internal/tools/hvsocketaddr/main.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"bytes"
+	"encoding/binary"
+	"fmt"
+	"os"
+	"strings"
+	"unicode/utf16"
+
+	"github.com/Microsoft/go-winio/pkg/guid"
+)
+
+func HCSIDToGUID(id string) (guid.GUID, error) {
+	var buf bytes.Buffer
+	if err := binary.Write(&buf, binary.LittleEndian, utf16.Encode([]rune(strings.ToUpper(id)))); err != nil {
+		return guid.GUID{}, err
+	}
+	// Namespace GUID: cab70344-facb-41e4-b5e5-ab6592283e6e
+	g, err := guid.NewV5(guid.GUID{Data1: 0xcab70344, Data2: 0xfacb, Data3: 0x41e4, Data4: [8]byte{0xb5, 0xe5, 0xab, 0x65, 0x92, 0x28, 0x3e, 0x6e}}, buf.Bytes())
+	if err != nil {
+		return guid.GUID{}, err
+	}
+	return g, nil
+}
+
+func main() {
+	if len(os.Args) != 2 || os.Args[1] == "--help" || os.Args[1] == "-h" {
+		fmt.Printf("usage: %s <CONTAINER ID>\n", os.Args[0])
+		os.Exit(1)
+	}
+	g, err := HCSIDToGUID(os.Args[1])
+	if err != nil {
+		fmt.Printf("error: %s\n", err)
+	}
+	fmt.Printf("%s\n", g)
+}