ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Linux-Clone/Clone.pm
Revision: 1.5
Committed: Mon Jul 25 10:59:29 2022 UTC (2 years, 3 months ago) by root
Branch: MAIN
Changes since 1.4: +1 -1 lines
Log Message:
*** empty log message ***

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 related syscalls to
12 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
36 Example: unshare the network namespace and prove that by calling ifconfig,
37 showing only an unconfigured lo interface.
38
39 Linux::Clone::unshare Linux::Clone::NEWNET
40 and "unshare: $!";
41 system "ifconfig -a";
42
43 Example: unshare the network namespace, initialise the loopback interface,
44 create a veth interface pair, put one interface into the parent processes
45 namespace (use ifconfig -a from another shell), configure the other
46 interface with 192.168.99.2 -> 192.168.99.1 and start a shell.
47
48 use Linux::Clone;
49
50 # unshare our network namespace
51 Linux::Clone::unshare Linux::Clone::NEWNET
52 and "unshare: $!";
53
54 my $ppid = getppid;
55
56 system "
57 # configure loopback interface
58 ip link set lo up
59 ip route add 127.0.0.0/8 dev lo
60
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 - 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::DETACHED
129 Linux::Clone::UNTRACED
130 Linux::Clone::IO
131
132 Note that for practical reasons you basically must not use
133 C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope
134 with that.
135
136 This is the glibc clone call, it cannot be used to emulate fork.
137
138 Example: do a fork-like clone, sharing nothing, slightly confusing perl
139 and your libc, and exit immediately.
140
141 my $pid = Linux::Clone::clone sub { warn "in child"; 77 }, 0, POSIX::SIGCHLD;
142
143 =item Linux::Clone::setns $fh_or_fd[, $nstype]
144
145 Calls setns(2) on the file descriptor (or file handle) C<$fh_or_fd>. If
146 C<$nstype> is missing, then C<0> is used.
147
148 The argument C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>,
149 C<Linux::Clone::NEWNET>, C<Linux::Clone::NEWUTS>, C<Linux::Clone::NEWCGROUP>,
150 C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>.
151
152 =item Linux::Clone::pivot_root $new_root, $old_root
153
154 Calls pivot_root(2) - refer to its manpage for details.
155
156 =item Linux::Clone::kcmp $pid1, $pid2, $type[, $idx1, $idx2]
157
158 Calls kcmp(2) - refer to its manpage for details on operations.
159
160 The following C<$type> constants are available if the kcmp syscall number
161 was available during compilation:
162
163 C<Linux::Clone::KCMP_FILE>, C<Linux::Clone::KCMP_VM>, C<Linux::Clone::KCMP_FILES>,
164 C<Linux::Clone::KCMP_FS>, C<Linux::Clone::KCMP_SIGHAND>, C<Linux::Clone::KCMP_IO> and
165 C<Linux::Clone::KCMP_SYSVSEM>.
166
167
168 =back
169
170 =cut
171
172 package Linux::Clone;
173
174 # use common::sense;
175
176 BEGIN {
177 our $VERSION = '1.2';
178
179 require XSLoader;
180 XSLoader::load (__PACKAGE__, $VERSION);
181 }
182
183 1;
184
185 =head1 AUTHOR
186
187 Marc Lehmann <schmorp@schmorp.de>
188 http://home.schmorp.de/
189
190 =cut
191