ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Linux-Clone/Clone.pm
Revision: 1.1
Committed: Mon Nov 28 05:43:03 2011 UTC (13 years ago) by root
Branch: MAIN
CVS Tags: rel-0_01
Log Message:
0.01

File Contents

# Content
1 =head1 NAME
2
3 Linux::Clone - an interface to the linux clone(2) and unshare(2) syscalls
4
5 =head1 SYNOPSIS
6
7 use Linux::Clone;
8
9 =head1 DESCRIPTION
10
11 This module exposes the linux clone(2) and unshare(2) 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::NEWUTS
30 Linux::Clone::NEWIPC
31 Linux::Clone::NEWNET
32
33 Example: unshare the network namespace and prove that by calling ifconfig,
34 showing only an unconfigured lo interface.
35
36 Linux::Clone::unshare Linux::Clone::NEWNET
37 and "unshare: $!";
38 system "ifconfig -a";
39
40 Example: unshare the network namespace, initialise the loopback interface,
41 create a veth interface pair, put one interface into the parent processes
42 namespace (use ifconfig -a from another shell), configure the other
43 interface with 192.168.99.2 -> 192.168.99.1 and start a shell.
44
45 use Linux::Clone;
46
47 # unshare our network namespace
48 Linux::Clone::unshare Linux::Clone::NEWNET
49 and "unshare: $!";
50
51 my $ppid = getppid;
52
53 system "
54 # configure loopback interface
55 ip link set lo up
56 ip route add 127.0.0.0/8 dev lo
57
58 # create veth pair
59 ip link add name veth_master type veth peer name veth_slave
60
61 # move veth_master to our parent process' namespace
62 ip link set veth_master netns $ppid
63
64 # configure the local interface
65 ip link set veth_slave up
66 ip addr add 192.168.99.2/32 dev veth_slave
67 ip route add 192.168.99.1/32 dev veth_slave
68 ";
69
70 print <<EOF;
71 say hi to your new network namespace, use exit to return.
72
73 try this from another shell to get networking up:
74
75 ip link set veth_master up
76 ip addr add 192.168.99.1/32 dev veth_master
77 ip route add 192.168.99.2/32 dev veth_master
78
79 EOF
80 system "bash";
81
82 Example: unshare the filesystem namespace and make a confusing bind mount
83 only visible to the current process.
84
85 use Linux::Clone;
86
87 Linux::Clone::unshare Linux::Clone::NEWNS
88 and die "unshare: $!";
89
90 # now bind-mount /lib over /etc and ls -l /etc - scary
91 system "mount -n --bind /lib /etc";
92 system "ls -l /etc";
93
94 =item $retval = Linux::Clone::clone $coderef, $stacksize, $flags[, $ptid, $tls, $ctid]
95
96 Clones a new process as specified via C<$flags> and calls C<$coderef>
97 without any arguments (a closure might help you if you need to pass
98 arguments without global variables). The return value from coderef is
99 returned to the system.
100
101 The C<$stacksize> specifies how large a stack to allocate for the
102 child. If it is C<0>, then a default stack size (currently 4MB) will be
103 allocated. There is currently no way to free this area again in the child.
104
105 C<$ptid>, if specified, will receive the thread id, C<$tls>, if specified,
106 must contain a C<struct user_desc> and C<$ctid> is currently totally
107 unsupported and must not be specified.
108
109 Since this call basically bypasses both perl and your libc (for example,
110 C<$$> might reflect the parent I<or> child pid in the child), you need to
111 be very careful when using this call, which means you should probably have
112 a very good understanding of perl memory management and how fork and clone
113 work.
114
115 The following flags are supported for clone, in addition to all flags
116 supported by C<unshare>, above, and a signal number. When in doubt, refer
117 to the clone(2) manual page.
118
119 Linux::Clone::PTRACE
120 Linux::Clone::VFORK
121 Linux::Clone::SETTLS (not yet implemented)
122 Linux::Clone::PARENT_SETTID (not yet implemented)
123 Linux::Clone::CHILD_SETTID (not yet implemented)
124 Linux::Clone::CHILD_CLEARTID (not yet implemented)
125 Linux::Clone::DETACHED
126 Linux::Clone::UNTRACED
127 Linux::Clone::NEWUSER
128 Linux::Clone::NEWPID
129 Linux::Clone::IO
130
131 Note that for practical reasons you basically must not use
132 C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope
133 with that.
134
135 This is the glibc clone call, it cannot be used to emulate fork.
136
137 Example: do a fork-like clone, sharing nothing, slightly confusing perl
138 and your libc, and exit immediately.
139
140 my $pid = Linux::Clone::clone sub { warn "in child"; 77 }, 0, POSIX::SIGCHLD;
141
142 =back
143
144 =cut
145
146 package Linux::Clone;
147
148 # use common::sense;
149
150 BEGIN {
151 our $VERSION = '0.01';
152
153 require XSLoader;
154 XSLoader::load (__PACKAGE__, $VERSION);
155 }
156
157 1;
158
159 =head1 AUTHOR
160
161 Marc Lehmann <schmorp@schmorp.de>
162 http://home.schmorp.de/
163
164 =cut
165