From 205063bc7c5e3741eeffdbe85b3e4a626b7f27e9 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 |  7 ++++++-
 docs/windows.md       | 40 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/cmd/buildkitd/main.go b/cmd/buildkitd/main.go
index cef6ad2a1f7e..4a0312d7e20f 100644
--- a/cmd/buildkitd/main.go
+++ b/cmd/buildkitd/main.go
@@ -150,6 +150,11 @@ func main() {
 		return strconv.Itoa(*gid)
 	}
 
+	groupUsageStr := "group (name or gid) which will own all Unix socket listening addresses"
+	if runtime.GOOS == "windows" {
+		groupUsageStr = "group name(s), comma-separated, which will have RW access to the named pipe listening addresses"
+	}
+
 	app.Flags = append(app.Flags,
 		cli.StringFlag{
 			Name:  "config",
@@ -182,7 +187,7 @@ func main() {
 		},
 		cli.StringFlag{
 			Name:  "group",
-			Usage: "group (name or gid) which will own all Unix socket listening addresses",
+			Usage: groupUsageStr,
 			Value: groupValue(defaultConf.GRPC.GID),
 		},
 		cli.StringFlag{
diff --git a/docs/windows.md b/docs/windows.md
index f05730ccf26b..e22968cee10e 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.