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/