blib/lib/Linux/Clone.pm

filter: Statementstmt 80.0% 4 / 5 Branchbran 0.0% 0 / 2 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 50.0% 1 / 2 Podpod 100% 1 / 1 totaltotal 60.0% 6 / 10 CC 2 SCAR 14.7
CC
2
Cov
57%
configure_loopback
6.0
BEGIN
1.0
CRAP 4.3
↑ Summary Clone.xs »
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
BranchTrueFalseTotal
&siocsifflags("lo") and die "Linux::Clone::configure_looopback: unable to bring up loopback interface: $!\n" 0 0 0
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  
↑ Summary Clone.xs »