Linux-Clone/Clone.pm

=head1 NAME

Linux::Clone - an interface to the linux clone(2) and unshare(2) syscalls

=head1 SYNOPSIS

 use Linux::Clone;

=head1 DESCRIPTION

This module exposes the linux clone(2) and unshare(2) syscalls to
Perl.

=over 4

=item $retval = unshare $flags

The following CLONE_ flag values (without CLONE_ prefix) are supported for
unshare, if found, in this release. See the documentation for unshare(2)
for more info on what they do:

   Linux::Clone::FILES
   Linux::Clone::FS
   Linux::Clone::NEWNS   (in unshare, implies FS)
   Linux::Clone::VM      (in unshare, implies SIGHAND)
   Linux::Clone::THREAD  (in unshare, implies VM, SIGHAND)
   Linux::Clone::SIGHAND
   Linux::Clone::SYSVSEM
   Linux::Clone::NEWUTS
   Linux::Clone::NEWIPC
   Linux::Clone::NEWNET

Example: unshare the network namespace and prove that by calling ifconfig,
showing only an unconfigured lo interface.

   Linux::Clone::unshare Linux::Clone::NEWNET
      and "unshare: $!";
   system "ifconfig -a";

Example: unshare the network namespace, initialise the loopback interface,
create a veth interface pair, put one interface into the parent processes
namespace (use ifconfig -a from another shell), configure the other
interface with 192.168.99.2 -> 192.168.99.1 and start a shell.

   use Linux::Clone;

   # unshare our network namespace
   Linux::Clone::unshare Linux::Clone::NEWNET
     and "unshare: $!";

   my $ppid = getppid;

   system "
      # configure loopback interface
      ip link set lo up
      ip route add 127.0.0.0/8 dev lo

      # create veth pair
      ip link add name veth_master type veth peer name veth_slave

      # move veth_master to our parent process' namespace
      ip link set veth_master netns $ppid

      # configure the local interface
      ip link set veth_slave up
      ip addr add 192.168.99.2/32 dev veth_slave
      ip route add 192.168.99.1/32 dev veth_slave
   ";

   print <<EOF;
   say hi to your new network namespace, use exit to return.

   try this from another shell to get networking up:

   ip link set veth_master up
   ip addr add 192.168.99.1/32 dev veth_master
   ip route add 192.168.99.2/32 dev veth_master

   EOF
   system "bash";

Example: unshare the filesystem namespace and make a confusing bind mount
only visible to the current process.

   use Linux::Clone;

   Linux::Clone::unshare Linux::Clone::NEWNS
      and die "unshare: $!";

   # now bind-mount /lib over /etc and ls -l /etc - scary
   system "mount -n --bind /lib /etc";
   system "ls -l /etc";

=item $retval = Linux::Clone::clone $coderef, $stacksize, $flags[, $ptid, $tls, $ctid]

Clones a new process as specified via C<$flags> and calls C<$coderef>
without any arguments (a closure might help you if you need to pass
arguments without global variables). The return value from coderef is
returned to the system.

The C<$stacksize> specifies how large a stack to allocate for the
child. If it is C<0>, then a default stack size (currently 4MB) will be
allocated. There is currently no way to free this area again in the child.

C<$ptid>, if specified, will receive the thread id, C<$tls>, if specified,
must contain a C<struct user_desc> and C<$ctid> is currently totally
unsupported and must not be specified.

Since this call basically bypasses both perl and your libc (for example,
C<$$> might reflect the parent I<or> child pid in the child), you need to
be very careful when using this call, which means you should probably have
a very good understanding of perl memory management and how fork and clone
work.

The following flags are supported for clone, in addition to all flags
supported by C<unshare>, above, and a signal number. When in doubt, refer
to the clone(2) manual page.

   Linux::Clone::PTRACE
   Linux::Clone::VFORK
   Linux::Clone::SETTLS         (not yet implemented)
   Linux::Clone::PARENT_SETTID  (not yet implemented)
   Linux::Clone::CHILD_SETTID   (not yet implemented)
   Linux::Clone::CHILD_CLEARTID (not yet implemented)
   Linux::Clone::DETACHED
   Linux::Clone::UNTRACED
   Linux::Clone::NEWUSER
   Linux::Clone::NEWPID
   Linux::Clone::IO

Note that for practical reasons you basically must not use
C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope
with that.

This is the glibc clone call, it cannot be used to emulate fork.

Example: do a fork-like clone, sharing nothing, slightly confusing perl
and your libc, and exit immediately.

   my $pid = Linux::Clone::clone sub { warn "in child"; 77 }, 0, POSIX::SIGCHLD;

=back

=cut

package Linux::Clone;

# use common::sense;

BEGIN {
   our $VERSION = '0.01';

   require XSLoader;
   XSLoader::load (__PACKAGE__, $VERSION);
}

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.1
Committed:	Mon Nov 28 05:43:03 2011 UTC (12 years, 5 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_01
Log Message:	0.01
#	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