ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Linux-Clone/Clone.pm
Revision: 1.10
Committed: Tue Sep 6 10:57:01 2022 UTC (2 years, 2 months ago) by root
Branch: MAIN
CVS Tags: rel-1_3, HEAD
Changes since 1.9: +4 -3 lines
Error occurred while calculating annotation data.
Log Message:
1.3

File Contents

# Content
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 BEGIN {
195 our $VERSION = '1.3';
196
197 require XSLoader;
198 XSLoader::load (__PACKAGE__, $VERSION);
199 }
200
201 sub configure_loopback() {
202 siocsifflags "lo"
203 and die "Linux::Clone::configure_looopback: unable to bring up loopback interface: $!\n";
204 }
205
206 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