diff --git a/cmd/buildkitd/main.go b/cmd/buildkitd/main.go index cef6ad2a1f7e5..025b9e374f305 100644 --- a/cmd/buildkitd/main.go +++ b/cmd/buildkitd/main.go @@ -182,7 +182,7 @@ func main() { }, cli.StringFlag{ Name: "group", - Usage: "group (name or gid) which will own all Unix socket listening addresses", + Usage: "group (name or gid) which will own all Unix socket or Windows named pipe listening addresses", Value: groupValue(defaultConf.GRPC.GID), }, cli.StringFlag{ diff --git a/docs/buildkitd.toml.md b/docs/buildkitd.toml.md index 665d97f936051..7db7f5c8dd655 100644 --- a/docs/buildkitd.toml.md +++ b/docs/buildkitd.toml.md @@ -35,6 +35,9 @@ insecure-entitlements = [ "network.host", "security.insecure" ] debugAddress = "0.0.0.0:6060" uid = 0 gid = 0 + # this is for Windows scenarios, to give RW access to the named pipe to specific users + # consider `buildkitd --group=""` as an easier option. + SecurityDescriptor = "D:P(A;;GA;;;BA)(A;;GA;;;SY)(A;;GRGW;;;S-1-5-21-xxx-xxx-3751290628-1002)" [grpc.tls] cert = "/etc/buildkit/tls.crt" key = "/etc/buildkit/tls.key" diff --git a/docs/windows.md b/docs/windows.md index f05730ccf26b7..e22968cee10ee 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -1,13 +1,13 @@ -**Table of Contents** - [Experimental Windows containers support](#experimental-windows-containers-support) - [Quick start guide](#quick-start-guide) - [Platform requirements](#platform-requirements) - [Setup Instructions](#setup-instructions) - [Example Build](#example-build) + - [Running `buildctl` from a Non-Admin Terminal](#running-buildctl-from-a-non-admin-terminal) @@ -145,3 +145,41 @@ Now that everything is setup, let's build a [simple _hello world_ image](https:/ ``` > **NOTE:** After pushing to the registry, you can use your image with any other clients to spin off containers, e.g. `docker run`, `ctr run`, `nerdctl run`, etc. + +## Running `buildctl` from a Non-Admin Terminal + +The default case for running `buildctl` is from an admin (elevated) terminal. +If you attempt running in a non-admin terminal, you will get an `Access Denied` +error, on the named pipe: + +``` +connection error: desc = "transport: Error while dialing: open \\\\.\\pipe\\buildkitd: Access is denied." +``` + +However, it is possible to run it in a non-admin terminal by providing +the group name(s) of the users executing the command. + +You can find the group names that the current user belongs too by running: + +```cmd +whoami /groups +``` + +You can also create a group and add the user on it by running the following in +an admin terminal: + +```powershell +# you can use $env:USERNAME for PowerShell or +# %USERNAME% for CMD terminal +net localgroup buildkit-users /add +``` +NOTE: You will need to log out and log in for the changes to reflect. + +Once you have the group(s), you can supply it as part of the `--group` flag when starting +`buildkitd` (still in an admin termainal). If it is more than one group, comma-separate them. Example: + +```powershell +buildkitd --group="USERBOX-1\buildkit-users" +``` + +With this now, you can run `buildctl` in a non-admin terminal.