github.com/thediveo/gons@v0.9.9/doc.go (about) 1 /* 2 Package gons ("go [into] namespaces") selectively switches your Go application 3 into other already existing Linux namespaces. This must happen before the Go 4 runtime spins up, because the Go runtime later unintentionally blocks certain 5 namespace changes, especially changing into a different mount namespace when 6 running with multiple OS threads. 7 8 # Using gons in Your Code 9 10 Simply import the gons package into your application, and you're almost set. 11 In your application's main() you should check that there were no errors 12 switching namespaces. 13 14 package main 15 16 import _ "github.com/thediveo/gons" 17 18 func main() { 19 if err := Status(); err != nil { 20 panic(err.Error()) 21 } 22 // ... 23 } 24 25 # Telling Your Program Which Namespaces to Enter 26 27 The existing namespaces to join/switch into are referenced by their paths in 28 the filesystem (such as "/proc/123456/ns/mnt"), and are specified using 29 environment variables. Set only the environment variables for those namespaces 30 that should be switched at startup. These variables need to be set before your 31 application is started. The names of the environment variables are as follows 32 and must be all lowercase: 33 34 gons_cgroup=... 35 gons_ipc=... 36 gons_mnt=... 37 gons_net=... 38 gons_pid=... # see note below 39 gons_user=... 40 gons_uts=... 41 42 # Controlling the Sequence in Which to Enter Namespaces 43 44 Additionally, you can specify the order in which the namespaces should be 45 switched, as well as when the namespace paths are to be opened: if not 46 overridden by the optional environment variable gons_order=..., then the 47 default order is "!user,!mnt,!cgroup,!ipc,!net,!pid,!uts" (see below for the 48 meaning of "!"). It's not necessary to specify all 7 namespace types when you 49 don't intend to switch them all. For instance, if you just switch the net and 50 IPC namespaces, then "gons_order=net,ipc" is sufficient. 51 52 When a namespace type name is preceded by a bang "!", such as "!user", then 53 the its path will be opened before the first namespace switch takes place. 54 Without a bang, the namespace path is opened just right before switching into 55 this namespace. This is mostly of importance when switching the mount 56 namespace, as this can also change the filesystem and thus how the namespace 57 paths are resolved. 58 59 # Reexec to the Rescue 60 61 In case your Go application wants to fork and then restart itself in order to 62 be able to switch namespaces, you might find the subpackage 63 "github.com/thediveo/gons/reexec" useful. It simplifies the overall process and 64 takes care of correctly setting the environment variables. 65 66 # Technical Notes 67 68 Setting "gons_pid=..."" does not switch your application's own PID namespace, but 69 rather controls the PID namespace any child processes of your application will 70 be put into. 71 72 If a given namespace path is invalid, or if there are insufficient rights to 73 access the path or switch to the specified namespace, then an error message is 74 printed to stderr and the application aborted with error code 1. 75 76 The gons package requires cgo (https://golang.org/cmd/cgo/): the required 77 namespace switches can only safely be done while your application is still 78 single-threaded and that's only the case before the Go runtime is spinning up. 79 */ 80 package gons