| 1 | =head1 NAME | ||||||||||
| 2 | |||||||||||
| 3 | Linux::Clone - an interface to the linux clone, unshare, setns, pivot_root and kcmp syscalls | ||||||||||
| 4 | |||||||||||
| 5 | =head1 SYNOPSIS | ||||||||||
| 6 | |||||||||||
| 7 | use Linux::Clone; | ||||||||||
| 8 | |||||||||||
| 9 | =head1 DESCRIPTION | ||||||||||
| 10 | |||||||||||
| 11 | This module exposes the linux clone(2), unshare(2) and some related | ||||||||||
| 12 | syscalls to Perl. | ||||||||||
| 13 | |||||||||||
| 14 | =over 4 | ||||||||||
| 15 | |||||||||||
| 16 | =item $retval = unshare $flags | ||||||||||
| 17 | |||||||||||
| 18 | The following CLONE_ flag values (without CLONE_ prefix) are supported for | ||||||||||
| 19 | unshare, if found, in this release. See the documentation for unshare(2) | ||||||||||
| 20 | for more info on what they do: | ||||||||||
| 21 | |||||||||||
| 22 | Linux::Clone::FILES | ||||||||||
| 23 | Linux::Clone::FS | ||||||||||
| 24 | Linux::Clone::NEWNS (in unshare, implies FS) | ||||||||||
| 25 | Linux::Clone::VM (in unshare, implies SIGHAND) | ||||||||||
| 26 | Linux::Clone::THREAD (in unshare, implies VM, SIGHAND) | ||||||||||
| 27 | Linux::Clone::SIGHAND | ||||||||||
| 28 | Linux::Clone::SYSVSEM | ||||||||||
| 29 | Linux::Clone::NEWUSER (in unshare, implies CLONE_THREAD) | ||||||||||
| 30 | Linux::Clone::NEWPID | ||||||||||
| 31 | Linux::Clone::NEWUTS | ||||||||||
| 32 | Linux::Clone::NEWIPC | ||||||||||
| 33 | Linux::Clone::NEWNET | ||||||||||
| 34 | Linux::Clone::NEWCGROUP | ||||||||||
| 35 | Linux::Clone::NEWTIME | ||||||||||
| 36 | |||||||||||
| 37 | Example: unshare the network namespace and prove that by calling ifconfig, | ||||||||||
| 38 | showing only the unconfigured lo interface. | ||||||||||
| 39 | |||||||||||
| 40 | Linux::Clone::unshare Linux::Clone::NEWNET | ||||||||||
| 41 | and "unshare: $!"; | ||||||||||
| 42 | Linux::Clone::configure_loopback; | ||||||||||
| 43 | system "ifconfig"; | ||||||||||
| 44 | |||||||||||
| 45 | Example: unshare the network namespace, initialise the loopback interface, | ||||||||||
| 46 | create a veth interface pair, put one interface into the parent processes | ||||||||||
| 47 | namespace (use ifconfig -a from another shell), configure the other | ||||||||||
| 48 | interface with 192.168.99.2 -> 192.168.99.1 and start a shell. | ||||||||||
| 49 | |||||||||||
| 50 | use Linux::Clone; | ||||||||||
| 51 | |||||||||||
| 52 | # unshare our network namespace | ||||||||||
| 53 | Linux::Clone::unshare Linux::Clone::NEWNET | ||||||||||
| 54 | and "unshare: $!"; | ||||||||||
| 55 | |||||||||||
| 56 | Linux::Clone::configure_loopback; | ||||||||||
| 57 | |||||||||||
| 58 | my $ppid = getppid; | ||||||||||
| 59 | |||||||||||
| 60 | system " | ||||||||||
| 61 | # create veth pair | ||||||||||
| 62 | ip link add name veth_master type veth peer name veth_slave | ||||||||||
| 63 | |||||||||||
| 64 | # move veth_master to our parent process' namespace | ||||||||||
| 65 | ip link set veth_master netns $ppid | ||||||||||
| 66 | |||||||||||
| 67 | # configure the local interface | ||||||||||
| 68 | ip link set veth_slave up | ||||||||||
| 69 | ip addr add 192.168.99.2/32 dev veth_slave | ||||||||||
| 70 | ip route add 192.168.99.1/32 dev veth_slave | ||||||||||
| 71 | "; | ||||||||||
| 72 | |||||||||||
| 73 | print <<EOF; | ||||||||||
| 74 | say hi to your new network namespace, use exit to return. | ||||||||||
| 75 | |||||||||||
| 76 | try this from another shell to get networking up: | ||||||||||
| 77 | |||||||||||
| 78 | ip link set veth_master up | ||||||||||
| 79 | ip addr add 192.168.99.1/32 dev veth_master | ||||||||||
| 80 | ip route add 192.168.99.2/32 dev veth_master | ||||||||||
| 81 | |||||||||||
| 82 | EOF | ||||||||||
| 83 | system "bash"; | ||||||||||
| 84 | |||||||||||
| 85 | Example: unshare the filesystem namespace and make a confusing bind mount | ||||||||||
| 86 | only visible to the current process. | ||||||||||
| 87 | |||||||||||
| 88 | use Linux::Clone; | ||||||||||
| 89 | |||||||||||
| 90 | Linux::Clone::unshare Linux::Clone::NEWNS | ||||||||||
| 91 | and die "unshare: $!"; | ||||||||||
| 92 | |||||||||||
| 93 | # now bind-mount /lib over /etc and ls -l /etc - looks scary | ||||||||||
| 94 | system "mount -n --bind /lib /etc"; | ||||||||||
| 95 | system "ls -l /etc"; | ||||||||||
| 96 | |||||||||||
| 97 | =item $retval = Linux::Clone::clone $coderef, $stacksize, $flags[, $ptid, $tls, $ctid] | ||||||||||
| 98 | |||||||||||
| 99 | Clones a new process as specified via C<$flags> and calls C<$coderef> | ||||||||||
| 100 | without any arguments (a closure might help you if you need to pass | ||||||||||
| 101 | arguments without global variables). The return value from coderef is | ||||||||||
| 102 | returned to the system. | ||||||||||
| 103 | |||||||||||
| 104 | The C<$stacksize> specifies how large a stack to allocate for the | ||||||||||
| 105 | child. If it is C<0>, then a default stack size (currently 4MB) will be | ||||||||||
| 106 | allocated. There is currently no way to free this area again in the child. | ||||||||||
| 107 | |||||||||||
| 108 | C<$ptid>, if specified, will receive the thread id, C<$tls>, if specified, | ||||||||||
| 109 | must contain a C<struct user_desc> and C<$ctid> is currently totally | ||||||||||
| 110 | unsupported and must not be specified. | ||||||||||
| 111 | |||||||||||
| 112 | Since this call basically bypasses both perl and your libc (for example, | ||||||||||
| 113 | C<$$> might reflect the parent I<or> child pid in the child), you need to | ||||||||||
| 114 | be very careful when using this call, which means you should probably have | ||||||||||
| 115 | a very good understanding of perl memory management and how fork and clone | ||||||||||
| 116 | work. | ||||||||||
| 117 | |||||||||||
| 118 | The following flags are supported for clone, in addition to all flags | ||||||||||
| 119 | supported by C<unshare>, above, and a signal number. When in doubt, refer | ||||||||||
| 120 | to the clone(2) manual page. | ||||||||||
| 121 | |||||||||||
| 122 | Linux::Clone::PTRACE | ||||||||||
| 123 | Linux::Clone::VFORK | ||||||||||
| 124 | Linux::Clone::SETTLS (not yet implemented) | ||||||||||
| 125 | Linux::Clone::PARENT_SETTID (not yet implemented) | ||||||||||
| 126 | Linux::Clone::CHILD_SETTID (not yet implemented) | ||||||||||
| 127 | Linux::Clone::CHILD_CLEARTID (not yet implemented) | ||||||||||
| 128 | Linux::Clone::PIDFD (not yet implemented) | ||||||||||
| 129 | Linux::Clone::DETACHED | ||||||||||
| 130 | Linux::Clone::UNTRACED | ||||||||||
| 131 | Linux::Clone::IO | ||||||||||
| 132 | Linux::Clone::CSIGNAL exit signal mask | ||||||||||
| 133 | |||||||||||
| 134 | Note that for practical reasons you basically must not use | ||||||||||
| 135 | C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope | ||||||||||
| 136 | with that. | ||||||||||
| 137 | |||||||||||
| 138 | This is the glibc clone call, it cannot be used to emulate fork. | ||||||||||
| 139 | |||||||||||
| 140 | Example: do a fork-like clone, sharing nothing, slightly confusing perl | ||||||||||
| 141 | and your libc, and exit immediately. | ||||||||||
| 142 | |||||||||||
| 143 | my $pid = Linux::Clone::clone sub { warn "in child"; 77 }, 0, POSIX::SIGCHLD; | ||||||||||
| 144 | |||||||||||
| 145 | =item Linux::Clone::setns $fh_or_fd[, $nstype] | ||||||||||
| 146 | |||||||||||
| 147 | Calls setns(2) on the file descriptor (or file handle) C<$fh_or_fd>. If | ||||||||||
| 148 | C<$nstype> is missing, then C<0> is used. | ||||||||||
| 149 | |||||||||||
| 150 | The argument C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>, | ||||||||||
| 151 | C<Linux::Clone::NEWNET>, C<Linux::Clone::NEWUTS>, C<Linux::Clone::NEWCGROUP>, | ||||||||||
| 152 | C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>. | ||||||||||
| 153 | |||||||||||
| 154 | =item Linux::Clone::pivot_root $new_root, $old_root | ||||||||||
| 155 | |||||||||||
| 156 | Calls pivot_root(2) - refer to its manpage for details. | ||||||||||
| 157 | |||||||||||
| 158 | =item Linux::Clone::kcmp $pid1, $pid2, $type[, $idx1, $idx2] | ||||||||||
| 159 | |||||||||||
| 160 | Calls kcmp(2) - refer to its manpage for details on operations. | ||||||||||
| 161 | |||||||||||
| 162 | The following C<$type> constants are available if the kcmp syscall number | ||||||||||
| 163 | was available during compilation: | ||||||||||
| 164 | |||||||||||
| 165 | C<Linux::Clone::KCMP_FILE>, C<Linux::Clone::KCMP_VM>, C<Linux::Clone::KCMP_FILES>, | ||||||||||
| 166 | C<Linux::Clone::KCMP_FS>, C<Linux::Clone::KCMP_SIGHAND>, C<Linux::Clone::KCMP_IO>, | ||||||||||
| 167 | C<Linux::Clone::KCMP_SYSVSEM> and C<Linux::Clone::KCMP_EPOLL_TFD>. | ||||||||||
| 168 | |||||||||||
| 169 | =item Linux::Clone::configure_loopback | ||||||||||
| 170 | |||||||||||
| 171 | Configures a working loopback interface (basically, does the equivalent of | ||||||||||
| 172 | "ifconfig lo up" which automatically adds ipv4/ipv6 addresses and routes), | ||||||||||
| 173 | which can be useful to get a network namespace going. | ||||||||||
| 174 | |||||||||||
| 175 | Dies on error and returns nothing. | ||||||||||
| 176 | |||||||||||
| 177 | =item C<ioctl> symbols | ||||||||||
| 178 | |||||||||||
| 179 | The following ioctl symbols are also provided by this module (see L<ioctl_ns(8)>). | ||||||||||
| 180 | |||||||||||
| 181 | Linux::Clone::NS_GET_USERNS | ||||||||||
| 182 | Linux::Clone::NS_GET_PARENT | ||||||||||
| 183 | Linux::Clone::NS_GET_NSTYPE | ||||||||||
| 184 | Linux::Clone::NS_OWNER_UID | ||||||||||
| 185 | |||||||||||
| 186 | =back | ||||||||||
| 187 | |||||||||||
| 188 | =cut | ||||||||||
| 189 | |||||||||||
| 190 | package Linux::Clone; | ||||||||||
| 191 | |||||||||||
| 192 | # use common::sense; | ||||||||||
| 193 | |||||||||||
| 194 | 1 | ▶ | BEGIN { | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 195 | 1 | our $VERSION = '1.4'; | |||||||||
| 196 | |||||||||||
| 197 | 1 | require XSLoader; | |||||||||
| 198 | 1 | XSLoader::load (__PACKAGE__, $VERSION); | |||||||||
| 199 | } | ||||||||||
| 200 | |||||||||||
| 201 | 0 | ▶ | sub configure_loopback() { | ||||||||
|
Subroutine
configure_loopback: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 202 | 0 | ▶ | siocsifflags "lo" | ||||||||
|
Branch: 1 branch
| |||||||||||
| 203 | and die "Linux::Clone::configure_looopback: unable to bring up loopback interface: $!\n"; | ||||||||||
| 204 | } | ||||||||||
| 205 | |||||||||||
| 206 | 1 | 1; | |||||||||
| 207 | |||||||||||
| 208 | =head1 SEE ALSO | ||||||||||
| 209 | |||||||||||
| 210 | L<IO::AIO> has some related functions, such as C<pidfd_send_signal>, and | ||||||||||
| 211 | some unrelated functions that might be useful. | ||||||||||
| 212 | |||||||||||
| 213 | L<namspaces(7)>, L<cgroup_namespaces(7)>, L<pid_namespaces(7)>, | ||||||||||
| 214 | L<user_namespaces(7)>, L<time_namespaces(7)>, L<ip-netns(8)>, | ||||||||||
| 215 | L<switch_root(8)>, L<ioctl_ns(2)>, L<lsns(8)>Q | ||||||||||
| 216 | |||||||||||
| 217 | =head1 AUTHOR | ||||||||||
| 218 | |||||||||||
| 219 | Marc Lehmann <schmorp@schmorp.de> | ||||||||||
| 220 | http://home.schmorp.de/ | ||||||||||
| 221 | |||||||||||
| 222 | =cut | ||||||||||
| 223 | |||||||||||