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