Linux-Clone/Clone.pm

=head1 NAME

Linux::Clone - an interface to the linux clone, unshare, setns, pivot_root and kcmp syscalls

=head1 SYNOPSIS

 use Linux::Clone;

=head1 DESCRIPTION

This module exposes the linux clone(2), unshare(2) and some related
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::NEWUSER (in unshare, implies CLONE_THREAD)
   Linux::Clone::NEWPID
   Linux::Clone::NEWUTS
   Linux::Clone::NEWIPC
   Linux::Clone::NEWNET
   Linux::Clone::NEWCGROUP
   Linux::Clone::NEWTIME

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

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

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: $!";

   Linux::Clone::configure_loopback;

   my $ppid = getppid;

   system "
      # 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 - looks 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::PIDFD          (not yet implemented)
   Linux::Clone::DETACHED
   Linux::Clone::UNTRACED
   Linux::Clone::IO
   Linux::Clone::CSIGNAL exit signal mask

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;

=item Linux::Clone::setns $fh_or_fd[, $nstype]

Calls setns(2) on the file descriptor (or file handle) C<$fh_or_fd>. If
C<$nstype> is missing, then C<0> is used.

The argument C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>,
C<Linux::Clone::NEWNET>, C<Linux::Clone::NEWUTS>, C<Linux::Clone::NEWCGROUP>,
C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>.

=item Linux::Clone::pivot_root $new_root, $old_root

Calls pivot_root(2) - refer to its manpage for details.

=item Linux::Clone::kcmp $pid1, $pid2, $type[, $idx1, $idx2]

Calls kcmp(2) - refer to its manpage for details on operations.

The following C<$type> constants are available if the kcmp syscall number
was available during compilation:

C<Linux::Clone::KCMP_FILE>, C<Linux::Clone::KCMP_VM>, C<Linux::Clone::KCMP_FILES>,
C<Linux::Clone::KCMP_FS>, C<Linux::Clone::KCMP_SIGHAND>, C<Linux::Clone::KCMP_IO>,
C<Linux::Clone::KCMP_SYSVSEM> and C<Linux::Clone::KCMP_EPOLL_TFD>.

=item Linux::Clone::configure_loopback

Configures a working loopback interface (basically, does the equivalent of
"ifconfig lo up" which automatically adds ipv4/ipv6 addresses and routes),
which can be useful to get a network namespace going.

Dies on error and returns nothing.

=item C<ioctl> symbols

The following ioctl symbols are also provided by this module (see L<ioctl_ns(8)>).

   Linux::Clone::NS_GET_USERNS
   Linux::Clone::NS_GET_PARENT
   Linux::Clone::NS_GET_NSTYPE
   Linux::Clone::NS_OWNER_UID

=back

=cut

package Linux::Clone;

# use common::sense;

BEGIN {
   our $VERSION = '1.3';

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

sub configure_loopback() {
   siocsifflags "lo"
      and die "Linux::Clone::configure_looopback: unable to bring up loopback interface: $!\n";
}

1;

=head1 SEE ALSO

L<IO::AIO> has some related functions, such as C<pidfd_send_signal>, and
some unrelated fucntions that might be useful.

L<cgroup_namespaces(7)>, L<pid_namespaces(7)>, L<user_namespaces(7)>, L<time_namespaces(7)>,
L<ip-netns(8)>, L<lsns(8)>, L<switch_root(8)>, L<ioctl_ns(2)>.

=head1 AUTHOR

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

=cut

Revision:	1.9
Committed:	Sun Sep 4 00:17:26 2022 UTC (20 months, 2 weeks ago) by root
Branch:	MAIN
Changes since 1.8:	+4 -3 lines
Log Message:	* empty log message *
#	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.6	This module exposes the linux clone(2), unshare(2) and some related
12			syscalls to Perl.
13	root	1.1
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.9	Linux::Clone::NEWTIME
36	root	1.1
37			Example: unshare the network namespace and prove that by calling ifconfig,
38	root	1.6	showing only the unconfigured lo interface.
39	root	1.1
40			Linux::Clone::unshare Linux::Clone::NEWNET
41			and "unshare: $!";
42	root	1.6	Linux::Clone::configure_loopback;
43			system "ifconfig";
44	root	1.1
45			Example: unshare the network namespace, initialise the loopback interface,
46			create a veth interface pair, put one interface into the parent processes
47			namespace (use ifconfig -a from another shell), configure the other
48			interface with 192.168.99.2 -> 192.168.99.1 and start a shell.
49
50			use Linux::Clone;
51
52			# unshare our network namespace
53			Linux::Clone::unshare Linux::Clone::NEWNET
54			and "unshare: $!";
55
56	root	1.6	Linux::Clone::configure_loopback;
57
58	root	1.1	my $ppid = getppid;
59
60			system "
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	root	1.6	# now bind-mount /lib over /etc and ls -l /etc - looks scary
94	root	1.1	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	root	1.6	Linux::Clone::PIDFD (not yet implemented)
129	root	1.1	Linux::Clone::DETACHED
130			Linux::Clone::UNTRACED
131			Linux::Clone::IO
132	root	1.6	Linux::Clone::CSIGNAL exit signal mask
133	root	1.1
134			Note that for practical reasons you basically must not use
135			C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope
136			with that.
137
138			This is the glibc clone call, it cannot be used to emulate fork.
139
140			Example: do a fork-like clone, sharing nothing, slightly confusing perl
141			and your libc, and exit immediately.
142
143			my $pid = Linux::Clone::clone sub { warn "in child"; 77 }, 0, POSIX::SIGCHLD;
144
145	root	1.2	=item Linux::Clone::setns $fh_or_fd[, $nstype]
146
147			Calls setns(2) on the file descriptor (or file handle) C<$fh_or_fd>. If
148			C<$nstype> is missing, then C<0> is used.
149
150	root	1.3	The argument C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>,
151	root	1.5	C<Linux::Clone::NEWNET>, C<Linux::Clone::NEWUTS>, C<Linux::Clone::NEWCGROUP>,
152	root	1.2	C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>.
153
154	root	1.3	=item Linux::Clone::pivot_root $new_root, $old_root
155
156			Calls pivot_root(2) - refer to its manpage for details.
157
158			=item Linux::Clone::kcmp $pid1, $pid2, $type[, $idx1, $idx2]
159
160			Calls kcmp(2) - refer to its manpage for details on operations.
161
162			The following C<$type> constants are available if the kcmp syscall number
163			was available during compilation:
164
165			C<Linux::Clone::KCMP_FILE>, C<Linux::Clone::KCMP_VM>, C<Linux::Clone::KCMP_FILES>,
166	root	1.9	C<Linux::Clone::KCMP_FS>, C<Linux::Clone::KCMP_SIGHAND>, C<Linux::Clone::KCMP_IO>,
167			C<Linux::Clone::KCMP_SYSVSEM> and C<Linux::Clone::KCMP_EPOLL_TFD>.
168	root	1.3
169	root	1.6	=item Linux::Clone::configure_loopback
170
171			Configures a working loopback interface (basically, does the equivalent of
172			"ifconfig lo up" which automatically adds ipv4/ipv6 addresses and routes),
173			which can be useful to get a network namespace going.
174
175			Dies on error and returns nothing.
176	root	1.3
177	root	1.8	=item C<ioctl> symbols
178
179			The following ioctl symbols are also provided by this module (see L<ioctl_ns(8)>).
180
181			Linux::Clone::NS_GET_USERNS
182			Linux::Clone::NS_GET_PARENT
183			Linux::Clone::NS_GET_NSTYPE
184			Linux::Clone::NS_OWNER_UID
185
186	root	1.1	=back
187
188			=cut
189
190			package Linux::Clone;
191
192			# use common::sense;
193
194			BEGIN {
195	root	1.6	our $VERSION = '1.3';
196	root	1.1
197			require XSLoader;
198			XSLoader::load (__PACKAGE__, $VERSION);
199			}
200
201	root	1.6	sub configure_loopback() {
202			siocsifflags "lo"
203			and die "Linux::Clone::configure_looopback: unable to bring up loopback interface: $!\n";
204			}
205
206	root	1.1	1;
207
208	root	1.7	=head1 SEE ALSO
209
210			L<IO::AIO> has some related functions, such as C<pidfd_send_signal>, and
211			some unrelated fucntions that might be useful.
212
213	root	1.9	L<cgroup_namespaces(7)>, L<pid_namespaces(7)>, L<user_namespaces(7)>, L<time_namespaces(7)>,
214	root	1.8	L<ip-netns(8)>, L<lsns(8)>, L<switch_root(8)>, L<ioctl_ns(2)>.
215
216	root	1.1	=head1 AUTHOR
217
218			Marc Lehmann <schmorp@schmorp.de>
219			http://home.schmorp.de/
220
221			=cut
222