From 50a87764277acd18a075a48f2cc6ba73f92fbc58 Mon Sep 17 00:00:00 2001
From: Anthony Nandaa <profnandaa@gmail.com>
Date: Thu, 25 Apr 2024 19:57:08 +0300
Subject: [PATCH] docs: add documetation for --group and SecurityDescriptor
 config

This commit is a follow up of #4875, documenting the user of
`--group` flag and `grpc.SecurityDescriptor` toml config.

Also does a minor fix on the `help` for `--group` to specify
Windows named pipe alongside Unix socket.

Signed-off-by: Anthony Nandaa <profnandaa@gmail.com>
---
 cmd/buildkitd/main.go  |  2 +-
 docs/buildkitd.toml.md |  3 +++
 docs/windows.md        | 40 +++++++++++++++++++++++++++++++++++++++-
 3 files changed, 43 insertions(+), 2 deletions(-)

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 @@
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 <!-- details here: https://github.com/thlorenz/doctoc -->
-**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)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -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 <username> /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.