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

# User Rev Content
1 root 1.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