From a49152bbc46bc4b01cd02ad56e75d5e622f1f5f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dan=20=C4=8Cerm=C3=A1k?= <dcermak@suse.com>
Date: Wed, 10 Nov 2021 11:25:32 +0100
Subject: [PATCH] Add simple documentation how to use c/image with podman's
 rootless mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

this fixes #1400

Signed-off-by: Dan Čermák <dcermak@suse.com>
---
 doc.go | 76 +++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 57 insertions(+), 19 deletions(-)

diff --git a/doc.go b/doc.go
index 367f25c728..3d0c435819 100644
--- a/doc.go
+++ b/doc.go
@@ -1,32 +1,70 @@
-// Package image provides libraries and commands to interact with containers images.
+// The package image provides libraries and commands to interact with container images.
 //
 //  package main
 //
 //  import (
-//   	"context"
-//  	"fmt"
+//	"context"
+//	"fmt"
 //
-//  	"github.com/containers/image/v5/docker"
+//	"github.com/containers/image/v5/docker"
 //  )
 //
 //  func main() {
-//  	ref, err := docker.ParseReference("//fedora")
-//  	if err != nil {
-//  		panic(err)
-//  	}
-//  	ctx := context.Background()
-//  	img, err := ref.NewImage(ctx, nil)
-//  	if err != nil {
-//  		panic(err)
-//  	}
-//  	defer img.Close()
-//  	b, _, err := img.Manifest(ctx)
-//  	if err != nil {
-//  		panic(err)
-//  	}
-//  	fmt.Printf("%s", string(b))
+//	ref, err := docker.ParseReference("//fedora")
+//	if err != nil {
+//		panic(err)
+//	}
+//	ctx := context.Background()
+//	img, err := ref.NewImage(ctx, nil)
+//	if err != nil {
+//		panic(err)
+//	}
+//	defer img.Close()
+//	b, _, err := img.Manifest(ctx)
+//	if err != nil {
+//		panic(err)
+//	}
+//	fmt.Printf("%s", string(b))
 //  }
 //
 //
+// ## Notes on running in rootless mode
+//
+// If your application shall run in rootless mode, for instance to be able to
+// read from podman's user storage, then the following additional steps have to
+// be performed at startup of your application:
+//
+//  package main
+//
+//  import (
+//  	"github.com/containers/storage/pkg/reexec"
+//	"github.com/syndtr/gocapability/capability"
+//  )
+//
+//  var neededCapabilities = []capability.Cap{
+//          capability.CAP_CHOWN,
+//          capability.CAP_DAC_OVERRIDE,
+//          capability.CAP_FOWNER,
+//          capability.CAP_FSETID,
+//          capability.CAP_MKNOD,
+//          capability.CAP_SETFCAP,
+//  }
+//
+//  func main() {
+//          	reexec.Init()
+//
+//        	capabilities, err := capability.NewPid(0)
+//		if err != nil {
+//			panic(err)
+// 		}
+//		for _, cap := range neededCapabilities {
+//			if !capabilities.Get(capability.EFFECTIVE, cap) {
+//				// We miss a capability we need, create a user namespaces
+//				unshare.MaybeReexecUsingUserNamespace(true)
+//			}
+//		}
+//  		// rest of your code follows here
+//  }
+//
 // TODO(runcom)
 package image