ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Linux-Clone/Clone.pm
Revision: 1.4
Committed: Tue Nov 7 18:15:29 2017 UTC (6 years, 11 months ago) by root
Branch: MAIN
CVS Tags: rel-1_2
Changes since 1.3: +1 -1 lines
Log Message:
1.2

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3 root 1.3 Linux::Clone - an interface to the linux clone, unshare, setns, pivot_root and kcmp syscalls
4 root 1.1
5     =head1 SYNOPSIS
6    
7     use Linux::Clone;
8    
9     =head1 DESCRIPTION
10    
11 root 1.2 This module exposes the linux clone(2), unshare(2) and related syscalls to
12 root 1.1 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 root 1.2 Linux::Clone::NEWUSER (in unshare, implies CLONE_THREAD)
30     Linux::Clone::NEWPID
31 root 1.1 Linux::Clone::NEWUTS
32     Linux::Clone::NEWIPC
33     Linux::Clone::NEWNET
34 root 1.2 Linux::Clone::NEWCGROUP
35 root 1.1
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 root 1.2 =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 root 1.3 The argument C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>,
149 root 1.2 C<Linux::Clone::NEWNET>, C<Linux::Clone::NEUTS>, C<Linux::Clone::NEWCGROUP>,
150     C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>.
151    
152 root 1.3 =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 root 1.1 =back
169    
170     =cut
171    
172     package Linux::Clone;
173    
174     # use common::sense;
175    
176     BEGIN {
177 root 1.4 our $VERSION = '1.2';
178 root 1.1
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