Add authctl docs

.github/workflows/qa.yaml

@@ -331,8 +331,10 @@ jobs:
           # Print executed commands to ease debugging
           set -x
 
+          echo "::group::Install llvm-symbolizer"
           # For llvm-symbolizer
           sudo apt-get install -y llvm
+          echo "::endgroup::"
 
           go test -C ./pam/internal -json -asan -gcflags=all="${GO_GC_FLAGS}" -failfast -timeout ${GO_TESTS_TIMEOUT} ./... | \
             gotestfmt --logfile "${AUTHD_TESTS_ARTIFACTS_PATH}/gotestfmt.pam-internal-asan.log" || exit_code=$?

cmd/authctl/group/group.go

@@ -0,0 +1,18 @@
+// Package group provides utilities for managing group operations.
+package group
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// GroupCmd is a command to perform group-related operations.
+var GroupCmd = &cobra.Command{
+	Use:   "group",
+	Short: "Commands related to groups",
+	Args:  cobra.NoArgs,
+	RunE:  func(cmd *cobra.Command, args []string) error { return cmd.Usage() },
+}
+
+func init() {
+	GroupCmd.AddCommand(setGIDCmd)
+}

cmd/authctl/group/group_test.go

@@ -0,0 +1,59 @@
+package group_test
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"testing"
+
+	"github.com/ubuntu/authd/internal/testutils"
+)
+
+var authctlPath string
+var daemonPath string
+
+func TestGroupCommand(t *testing.T) {
+	t.Parallel()
+
+	tests := map[string]struct {
+		args             []string
+		expectedExitCode int
+	}{
+		"Usage_message_when_no_args": {expectedExitCode: 0},
+		"Help_flag":                  {args: []string{"--help"}, expectedExitCode: 0},
+
+		"Error_on_invalid_command": {args: []string{"invalid-command"}, expectedExitCode: 1},
+		"Error_on_invalid_flag":    {args: []string{"--invalid-flag"}, expectedExitCode: 1},
+	}
+
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			//nolint:gosec // G204 it's safe to use exec.Command with a variable here
+			cmd := exec.Command(authctlPath, append([]string{"group"}, tc.args...)...)
+			testutils.CheckCommand(t, cmd, tc.expectedExitCode)
+		})
+	}
+}
+
+func TestMain(m *testing.M) {
+	var authctlCleanup func()
+	var err error
+	authctlPath, authctlCleanup, err = testutils.BuildAuthctl()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Setup: %v\n", err)
+		os.Exit(1)
+	}
+	defer authctlCleanup()
+
+	var daemonCleanup func()
+	daemonPath, daemonCleanup, err = testutils.BuildAuthdWithExampleBroker()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Setup: %v\n", err)
+		os.Exit(1)
+	}
+	defer daemonCleanup()
+
+	m.Run()
+}

cmd/authctl/group/set-gid.go

@@ -0,0 +1,76 @@
+package group
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+
+	"github.com/spf13/cobra"
+	"github.com/ubuntu/authd/cmd/authctl/internal/client"
+	"github.com/ubuntu/authd/cmd/authctl/internal/completion"
+	"github.com/ubuntu/authd/internal/proto/authd"
+)
+
+// setGIDCmd is a command to set the GID of a group managed by authd.
+var setGIDCmd = &cobra.Command{
+	Use:   "set-gid <name> <gid>",
+	Short: "Set the GID of a group managed by authd",
+	Long: `Set the GID of a group managed by authd to the specified value.
+
+The new GID must be unique and non-negative. The command must be run as root.
+
+When a group's GID is changed, any users whose primary group is set to this
+group will have the GID of their primary group updated. The home directories of
+these users, and any files within these directories that are owned by the group,
+will be updated to the new GID.
+
+Files outside users' home directories are not updated and must be changed
+manually. Note that changing a GID can be unsafe if files on the system are
+still owned by the original GID: those files may become accessible to a
+different group that is later assigned that GID. To change group ownership of
+all files on the system from the old GID to the new GID, run:
+
+    sudo chown -R --from :OLD_GID :NEW_GID /
+
+`,
+	Example: `  # Set the GID of group "staff" to 30000
+  authctl group set-gid staff 30000`,
+	Args:              cobra.ExactArgs(2),
+	ValidArgsFunction: completion.Groups,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		name := args[0]
+		gidStr := args[1]
+		gid, err := strconv.ParseUint(gidStr, 10, 32)
+		if err != nil {
+			// Remove the "strconv.ParseUint: parsing ..." part from the error message
+			// because it doesn't add any useful information.
+			if unwrappedErr := errors.Unwrap(err); unwrappedErr != nil {
+				err = unwrappedErr
+			}
+			return fmt.Errorf("failed to parse GID %q: %w", gidStr, err)
+		}
+
+		client, err := client.NewUserServiceClient()
+		if err != nil {
+			return err
+		}
+
+		resp, err := client.SetGroupID(context.Background(), &authd.SetGroupIDRequest{
+			Name: name,
+			Id:   uint32(gid),
+			Lang: os.Getenv("LANG"),
+		})
+		if err != nil {
+			return err
+		}
+
+		// Print any warnings returned by the server.
+		for _, warning := range resp.Warnings {
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", warning)
+		}
+
+		return nil
+	},
+}

cmd/authctl/group/set-gid_test.go

@@ -0,0 +1,87 @@
+package group_test
+
+import (
+	"math"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/ubuntu/authd/internal/testutils"
+	"google.golang.org/grpc/codes"
+)
+
+func TestSetGIDCommand(t *testing.T) {
+	// We can't run these tests in parallel because the daemon with the example
+	// broker which we're using here uses userslocking.Z_ForTests_OverrideLocking()
+	// which makes userslocking.WriteLock() return an error immediately when the lock
+	// is already held - unlike the normal behavior which tries to acquire the lock
+	// for 15 seconds before returning an error.
+
+	daemonSocket := testutils.StartAuthd(t, daemonPath,
+		testutils.WithGroupFile(filepath.Join("testdata", "empty.group")),
+		testutils.WithPreviousDBState("one_user_and_group"),
+		testutils.WithCurrentUserAsRoot,
+	)
+
+	err := os.Setenv("AUTHD_SOCKET", daemonSocket)
+	require.NoError(t, err, "Failed to set AUTHD_SOCKET environment variable")
+
+	tests := map[string]struct {
+		args             []string
+		authdUnavailable bool
+
+		expectedExitCode int
+	}{
+		"Set_group_gid_success": {
+			args:             []string{"set-gid", "group1", "123456"},
+			expectedExitCode: 0,
+		},
+
+		"Error_when_group_does_not_exist": {
+			args:             []string{"set-gid", "invalidgroup", "123456"},
+			expectedExitCode: int(codes.NotFound),
+		},
+		"Error_when_gid_is_invalid": {
+			args:             []string{"set-gid", "group1", "invalidgid"},
+			expectedExitCode: 1,
+		},
+		"Error_when_gid_is_too_large": {
+			args:             []string{"set-gid", "group1", strconv.Itoa(math.MaxInt32 + 1)},
+			expectedExitCode: int(codes.Unknown),
+		},
+		"Error_when_gid_is_already_taken": {
+			args:             []string{"set-gid", "group1", "0"},
+			expectedExitCode: int(codes.Unknown),
+		},
+		"Error_when_gid_is_negative": {
+			args:             []string{"set-gid", "group1", "-1000"},
+			expectedExitCode: 1,
+		},
+		"Error_when_authd_is_unavailable": {
+			args:             []string{"set-gid", "group1", "123456"},
+			authdUnavailable: true,
+			expectedExitCode: int(codes.Unavailable),
+		},
+	}
+
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			if tc.authdUnavailable {
+				origValue := os.Getenv("AUTHD_SOCKET")
+				err := os.Setenv("AUTHD_SOCKET", "/non-existent")
+				require.NoError(t, err, "Failed to set AUTHD_SOCKET environment variable")
+				t.Cleanup(func() {
+					err := os.Setenv("AUTHD_SOCKET", origValue)
+					require.NoError(t, err, "Failed to restore AUTHD_SOCKET environment variable")
+				})
+			}
+
+			//nolint:gosec // G204 it's safe to use exec.Command with a variable here
+			cmd := exec.Command(authctlPath, append([]string{"group"}, tc.args...)...)
+			testutils.CheckCommand(t, cmd, tc.expectedExitCode)
+		})
+	}
+}

cmd/authctl/group/testdata/db/one_user_and_group.db.yaml

@@ -0,0 +1,17 @@
+users:
+    - name: user1
+      uid: 1111
+      gid: 11111
+      gecos: |-
+        User1 gecos
+        On multiple lines
+      dir: /home/user1
+      shell: /bin/bash
+      broker_id: broker-id
+groups:
+    - name: group1
+      gid: 11111
+      ugid: "12345678"
+users_to_groups:
+    - uid: 1111
+      gid: 11111

cmd/authctl/group/testdata/golden/TestGroupCommand/Error_on_invalid_command

@@ -0,0 +1,13 @@
+Usage:
+  authctl group [flags]
+  authctl group [command]
+
+Available Commands:
+  set-gid     Set the GID of a group managed by authd
+
+Flags:
+  -h, --help   help for group
+
+Use "authctl group [command] --help" for more information about a command.
+
+unknown command "invalid-command" for "authctl group"

cmd/authctl/group/testdata/golden/TestGroupCommand/Error_on_invalid_flag

@@ -0,0 +1,13 @@
+Usage:
+  authctl group [flags]
+  authctl group [command]
+
+Available Commands:
+  set-gid     Set the GID of a group managed by authd
+
+Flags:
+  -h, --help   help for group
+
+Use "authctl group [command] --help" for more information about a command.
+
+unknown flag: --invalid-flag

cmd/authctl/group/testdata/golden/TestGroupCommand/Help_flag

@@ -0,0 +1,13 @@
+Commands related to groups
+
+Usage:
+  authctl group [flags]
+  authctl group [command]
+
+Available Commands:
+  set-gid     Set the GID of a group managed by authd
+
+Flags:
+  -h, --help   help for group
+
+Use "authctl group [command] --help" for more information about a command.

cmd/authctl/group/testdata/golden/TestGroupCommand/Usage_message_when_no_args

@@ -0,0 +1,11 @@
+Usage:
+  authctl group [flags]
+  authctl group [command]
+
+Available Commands:
+  set-gid     Set the GID of a group managed by authd
+
+Flags:
+  -h, --help   help for group
+
+Use "authctl group [command] --help" for more information about a command.

cmd/authctl/group/testdata/golden/TestSetGIDCommand/Error_when_authd_is_unavailable

@@ -0,0 +1 @@
+Error: connection error: desc = "transport: Error while dialing: dial unix /non-existent: connect: no such file or directory"

cmd/authctl/group/testdata/golden/TestSetGIDCommand/Error_when_gid_is_already_taken

@@ -0,0 +1 @@
+Error: GID 0 already exists

cmd/authctl/group/testdata/golden/TestSetGIDCommand/Error_when_gid_is_invalid

@@ -0,0 +1 @@
+failed to parse GID "invalidgid": invalid syntax

cmd/authctl/group/testdata/golden/TestSetGIDCommand/Error_when_gid_is_negative

@@ -0,0 +1,7 @@
+Usage:
+  authctl group set-gid <name> <gid> [flags]
+
+Flags:
+  -h, --help   help for set-gid
+
+unknown shorthand flag: '1' in -1000

cmd/authctl/group/testdata/golden/TestSetGIDCommand/Error_when_gid_is_too_large

@@ -0,0 +1 @@
+Error: GID 2147483648 is too large to convert to int32

cmd/authctl/group/testdata/golden/TestSetGIDCommand/Error_when_group_does_not_exist

@@ -0,0 +1 @@
+Error: group "invalidgroup" not found

cmd/authctl/internal/client/client.go

@@ -0,0 +1,35 @@
+// Package client provides a utility function to create a gRPC client for the authd service.
+package client
+
+import (
+	"fmt"
+	"os"
+	"regexp"
+
+	"github.com/ubuntu/authd/internal/consts"
+	"github.com/ubuntu/authd/internal/proto/authd"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+)
+
+// NewUserServiceClient creates and returns a new [authd.UserServiceClient].
+func NewUserServiceClient() (authd.UserServiceClient, error) {
+	authdSocket := os.Getenv("AUTHD_SOCKET")
+	if authdSocket == "" {
+		authdSocket = "unix://" + consts.DefaultSocketPath
+	}
+
+	// Check if the socket has a scheme, else default to "unix://"
+	schemeRegex := regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9+.-]*:`)
+	if !schemeRegex.MatchString(authdSocket) {
+		authdSocket = "unix://" + authdSocket
+	}
+
+	conn, err := grpc.NewClient(authdSocket, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		return nil, fmt.Errorf("failed to connect to authd: %w", err)
+	}
+
+	client := authd.NewUserServiceClient(conn)
+	return client, nil
+}