NAME

Sys::Linux::Namespace - A Module for setting up linux namespaces

SYNOPSIS

use Sys::Linux::Namespace;

# Create a namespace with a private /tmp
my $ns1 = Sys::Linux::Namespace->new(private_tmp => 1);

$ns1->run(code => sub {
    # This code has it's own completely private /tmp filesystem
    open(my $fh, "</tmp/private");
    print $fh "Hello Void";
});	

# The private /tmp has been destroyed and we're back to our previous state

# Let's do it again, but this time with a private PID space too
my $ns2 = Sys::Linux::Namespace->new(private_tmp => 1, private_pid => 1);
$ns2->run(code => sub {
    # I will only see PID 1.  I can fork anything I want and they will only see me
    # if I die they  die too.
    use Data::Dumper;
    print Dumper([glob "/proc/*"]);
});
# We're back to our previous global /tmp and PID namespace
# all processes and private filesystems have been removed

# Now let's set up a private /tmp for the rest of the process 
$ns1->setup();
# We're now permanently (for this process) using a private /tmp.

REQUIREMENTS

This module requires your script to have CAP_SYS_ADMIN, usually by running as root. Without that it will fail to setup the namespaces and cause your program to exit.

METHODS

new

Construct a new Sys::Linux::Namespace object. This collects all the options you want to enable, but does not engage them.

All arguments are passed in like a hash. This module uses Moo to build up the object, so all the below attributes can also be accessed on the instantiated object too.

private_mount

Setup a private mount namespace, this makes every currently mounted filesystem private to our process. This means we can unmount and mount new filesystems without other processes seeing the mounts.

private_tmp

Sets up the private mount namespace as above, but also automatically sets up /tmp to be a clean private tmpfs mount. Takes either a true value, or a hashref with options to pass to the mount syscall. See man 8 mount for a list of possible options.

private_pid

Create a private PID namespace. This requires the use of ->run(). This requires a code parameter either to new() or to setup() Also sets up a private /proc mount by default

term_child

Send a term signal to the child process on any signal, followed shortly by a kill signal. This is the default behavior to prevent zombied processes.

no_proc

Don't setup a private /proc mount when doing private_pid

private_net

TODO This is not yet implemented. Once done however, it will allow a child process to execute with a private network preventing communication. Will require a code parameter to new() or setup.

private_ipc

Create a private IPC namespace.

private_user

Create a new user namespace. See man 7 user_namespaces for more information.

private_uts

Create a new UTS namespace. This will let you safely change the hostname of the system without affect anyone else.

private_sysvsem

Create a new System V Semaphore namespace. This will let you create new semaphores without anyone else touching them.

setup

Engage the namespaces with all the configured options. This does not fork, and affects the existing process. The changes cannot be undone.

run

Engage the namespaces on an unsuspecting coderef. Arguments are passed in like a hash. This will perform a fork to run the coderef in the new namespaces

code

The coderef to run. It will receive all arguments passed to ->run() as a hash.

Debugging

If $Sys::Linux::Namespace::debug is set to a true value, then some debugging messages will be sent to STDERR

AUTHOR

Ryan Voots simcop@cpan.org