NAME

Linux::Clone - an interface to the linux clone, unshare, setns, pivot_root and kcmp syscalls

SYNOPSIS

use Linux::Clone;

DESCRIPTION

This module exposes the linux clone(2), unshare(2) and some related syscalls to Perl.

$retval = unshare $flags

The following CLONE_ flag values (without CLONE_ prefix) are supported for unshare, if found, in this release. See the documentation for unshare(2) for more info on what they do:

Linux::Clone::FILES
Linux::Clone::FS
Linux::Clone::NEWNS   (in unshare, implies FS)
Linux::Clone::VM      (in unshare, implies SIGHAND)
Linux::Clone::THREAD  (in unshare, implies VM, SIGHAND)
Linux::Clone::SIGHAND
Linux::Clone::SYSVSEM
Linux::Clone::NEWUSER (in unshare, implies CLONE_THREAD)
Linux::Clone::NEWPID
Linux::Clone::NEWUTS
Linux::Clone::NEWIPC
Linux::Clone::NEWNET
Linux::Clone::NEWCGROUP
Linux::Clone::NEWTIME

Example: unshare the network namespace and prove that by calling ifconfig, showing only the unconfigured lo interface.

Linux::Clone::unshare Linux::Clone::NEWNET
   and "unshare: $!";
Linux::Clone::configure_loopback;
system "ifconfig";

Example: unshare the network namespace, initialise the loopback interface, create a veth interface pair, put one interface into the parent processes namespace (use ifconfig -a from another shell), configure the other interface with 192.168.99.2 -> 192.168.99.1 and start a shell.

use Linux::Clone;

# unshare our network namespace
Linux::Clone::unshare Linux::Clone::NEWNET
  and "unshare: $!";

Linux::Clone::configure_loopback;

my $ppid = getppid;

system "
   # create veth pair
   ip link add name veth_master type veth peer name veth_slave

   # move veth_master to our parent process' namespace
   ip link set veth_master netns $ppid

   # configure the local interface
   ip link set veth_slave up
   ip addr add 192.168.99.2/32 dev veth_slave
   ip route add 192.168.99.1/32 dev veth_slave
";

print <<EOF;
say hi to your new network namespace, use exit to return.

try this from another shell to get networking up:

ip link set veth_master up
ip addr add 192.168.99.1/32 dev veth_master
ip route add 192.168.99.2/32 dev veth_master

EOF
system "bash";

Example: unshare the filesystem namespace and make a confusing bind mount only visible to the current process.

use Linux::Clone;

Linux::Clone::unshare Linux::Clone::NEWNS
   and die "unshare: $!";

# now bind-mount /lib over /etc and ls -l /etc - looks scary
system "mount -n --bind /lib /etc";
system "ls -l /etc";

$retval = Linux::Clone::clone $coderef, $stacksize, $flags[, $ptid, $tls, $ctid]

Clones a new process as specified via $flags and calls $coderef without any arguments (a closure might help you if you need to pass arguments without global variables). The return value from coderef is returned to the system.

The $stacksize specifies how large a stack to allocate for the child. If it is 0, then a default stack size (currently 4MB) will be allocated. There is currently no way to free this area again in the child.

$ptid, if specified, will receive the thread id, $tls, if specified, must contain a struct user_desc and $ctid is currently totally unsupported and must not be specified.

Since this call basically bypasses both perl and your libc (for example, $$ might reflect the parent or child pid in the child), you need to be very careful when using this call, which means you should probably have a very good understanding of perl memory management and how fork and clone work.

The following flags are supported for clone, in addition to all flags supported by unshare, above, and a signal number. When in doubt, refer to the clone(2) manual page.

Linux::Clone::PTRACE
Linux::Clone::VFORK
Linux::Clone::SETTLS         (not yet implemented)
Linux::Clone::PARENT_SETTID  (not yet implemented)
Linux::Clone::CHILD_SETTID   (not yet implemented)
Linux::Clone::CHILD_CLEARTID (not yet implemented)
Linux::Clone::PIDFD          (not yet implemented)
Linux::Clone::DETACHED
Linux::Clone::UNTRACED
Linux::Clone::IO
Linux::Clone::CSIGNAL exit signal mask

Note that for practical reasons you basically must not use Linux::Clone::VM or Linux::Clone::VFORK, as perl is unlikely to cope with that.

This is the glibc clone call, it cannot be used to emulate fork.

Example: do a fork-like clone, sharing nothing, slightly confusing perl and your libc, and exit immediately.

my $pid = Linux::Clone::clone sub { warn "in child"; 77 }, 0, POSIX::SIGCHLD;

Linux::Clone::setns $fh_or_fd[, $nstype]

Calls setns(2) on the file descriptor (or file handle) $fh_or_fd. If $nstype is missing, then 0 is used.

The argument $nstype can be 0, Linux::Clone::NEWIPC, Linux::Clone::NEWNET, Linux::Clone::NEWUTS, Linux::Clone::NEWCGROUP, Linux::Clone::NEWNS, Linux::Clone::NEWPID or Linux::Clone::NEWUSER.

Linux::Clone::pivot_root $new_root, $old_root

Calls pivot_root(2) - refer to its manpage for details.

Linux::Clone::kcmp $pid1, $pid2, $type[, $idx1, $idx2]

Calls kcmp(2) - refer to its manpage for details on operations.

The following $type constants are available if the kcmp syscall number was available during compilation:

Linux::Clone::KCMP_FILE, Linux::Clone::KCMP_VM, Linux::Clone::KCMP_FILES, Linux::Clone::KCMP_FS, Linux::Clone::KCMP_SIGHAND, Linux::Clone::KCMP_IO, Linux::Clone::KCMP_SYSVSEM and Linux::Clone::KCMP_EPOLL_TFD.

Linux::Clone::configure_loopback

Configures a working loopback interface (basically, does the equivalent of "ifconfig lo up" which automatically adds ipv4/ipv6 addresses and routes), which can be useful to get a network namespace going.

Dies on error and returns nothing.

ioctl symbols

The following ioctl symbols are also provided by this module (see ioctl_ns(8)).

Linux::Clone::NS_GET_USERNS
Linux::Clone::NS_GET_PARENT
Linux::Clone::NS_GET_NSTYPE
Linux::Clone::NS_OWNER_UID

SEE ALSO

IO::AIO has some related functions, such as pidfd_send_signal, and some unrelated functions that might be useful.

namspaces(7), cgroup_namespaces(7), pid_namespaces(7), user_namespaces(7), time_namespaces(7), ip-netns(8), switch_root(8), ioctl_ns(2), lsns(8)Q

AUTHOR

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/