ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Linux-Clone/Clone.pm
(Generate patch)

Comparing Linux-Clone/Clone.pm (file contents):
Revision 1.2 by root, Wed Aug 24 03:34:24 2016 UTC vs.
Revision 1.9 by root, Sun Sep 4 00:17:26 2022 UTC

1=head1 NAME 1=head1 NAME
2 2
3Linux::Clone - an interface to the linux clone(2) and unshare(2) syscalls 3Linux::Clone - an interface to the linux clone, unshare, setns, pivot_root and kcmp syscalls
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Linux::Clone; 7 use Linux::Clone;
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11This module exposes the linux clone(2), unshare(2) and related syscalls to 11This module exposes the linux clone(2), unshare(2) and some related
12Perl. 12syscalls to Perl.
13 13
14=over 4 14=over 4
15 15
16=item $retval = unshare $flags 16=item $retval = unshare $flags
17 17
… …
30 Linux::Clone::NEWPID 30 Linux::Clone::NEWPID
31 Linux::Clone::NEWUTS 31 Linux::Clone::NEWUTS
32 Linux::Clone::NEWIPC 32 Linux::Clone::NEWIPC
33 Linux::Clone::NEWNET 33 Linux::Clone::NEWNET
34 Linux::Clone::NEWCGROUP 34 Linux::Clone::NEWCGROUP
35 Linux::Clone::NEWTIME
35 36
36Example: unshare the network namespace and prove that by calling ifconfig, 37Example: unshare the network namespace and prove that by calling ifconfig,
37showing only an unconfigured lo interface. 38showing only the unconfigured lo interface.
38 39
39 Linux::Clone::unshare Linux::Clone::NEWNET 40 Linux::Clone::unshare Linux::Clone::NEWNET
40 and "unshare: $!"; 41 and "unshare: $!";
42 Linux::Clone::configure_loopback;
41 system "ifconfig -a"; 43 system "ifconfig";
42 44
43Example: unshare the network namespace, initialise the loopback interface, 45Example: unshare the network namespace, initialise the loopback interface,
44create a veth interface pair, put one interface into the parent processes 46create a veth interface pair, put one interface into the parent processes
45namespace (use ifconfig -a from another shell), configure the other 47namespace (use ifconfig -a from another shell), configure the other
46interface with 192.168.99.2 -> 192.168.99.1 and start a shell. 48interface with 192.168.99.2 -> 192.168.99.1 and start a shell.
… …
49 51
50 # unshare our network namespace 52 # unshare our network namespace
51 Linux::Clone::unshare Linux::Clone::NEWNET 53 Linux::Clone::unshare Linux::Clone::NEWNET
52 and "unshare: $!"; 54 and "unshare: $!";
53 55
56 Linux::Clone::configure_loopback;
57
54 my $ppid = getppid; 58 my $ppid = getppid;
55 59
56 system " 60 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 61 # create veth pair
62 ip link add name veth_master type veth peer name veth_slave 62 ip link add name veth_master type veth peer name veth_slave
63 63
64 # move veth_master to our parent process' namespace 64 # move veth_master to our parent process' namespace
65 ip link set veth_master netns $ppid 65 ip link set veth_master netns $ppid
… …
88 use Linux::Clone; 88 use Linux::Clone;
89 89
90 Linux::Clone::unshare Linux::Clone::NEWNS 90 Linux::Clone::unshare Linux::Clone::NEWNS
91 and die "unshare: $!"; 91 and die "unshare: $!";
92 92
93 # now bind-mount /lib over /etc and ls -l /etc - scary 93 # now bind-mount /lib over /etc and ls -l /etc - looks scary
94 system "mount -n --bind /lib /etc"; 94 system "mount -n --bind /lib /etc";
95 system "ls -l /etc"; 95 system "ls -l /etc";
96 96
97=item $retval = Linux::Clone::clone $coderef, $stacksize, $flags[, $ptid, $tls, $ctid] 97=item $retval = Linux::Clone::clone $coderef, $stacksize, $flags[, $ptid, $tls, $ctid]
98 98
… …
123 Linux::Clone::VFORK 123 Linux::Clone::VFORK
124 Linux::Clone::SETTLS (not yet implemented) 124 Linux::Clone::SETTLS (not yet implemented)
125 Linux::Clone::PARENT_SETTID (not yet implemented) 125 Linux::Clone::PARENT_SETTID (not yet implemented)
126 Linux::Clone::CHILD_SETTID (not yet implemented) 126 Linux::Clone::CHILD_SETTID (not yet implemented)
127 Linux::Clone::CHILD_CLEARTID (not yet implemented) 127 Linux::Clone::CHILD_CLEARTID (not yet implemented)
128 Linux::Clone::PIDFD (not yet implemented)
128 Linux::Clone::DETACHED 129 Linux::Clone::DETACHED
129 Linux::Clone::UNTRACED 130 Linux::Clone::UNTRACED
130 Linux::Clone::IO 131 Linux::Clone::IO
132 Linux::Clone::CSIGNAL exit signal mask
131 133
132Note that for practical reasons you basically must not use 134Note that for practical reasons you basically must not use
133C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope 135C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope
134with that. 136with that.
135 137
… …
143=item Linux::Clone::setns $fh_or_fd[, $nstype] 145=item Linux::Clone::setns $fh_or_fd[, $nstype]
144 146
145Calls setns(2) on the file descriptor (or file handle) C<$fh_or_fd>. If 147Calls setns(2) on the file descriptor (or file handle) C<$fh_or_fd>. If
146C<$nstype> is missing, then C<0> is used. 148C<$nstype> is missing, then C<0> is used.
147 149
148At the time of this writing, C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>, 150The argument C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>,
149C<Linux::Clone::NEWNET>, C<Linux::Clone::NEUTS>, C<Linux::Clone::NEWCGROUP>, 151C<Linux::Clone::NEWNET>, C<Linux::Clone::NEWUTS>, C<Linux::Clone::NEWCGROUP>,
150C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>. 152C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>.
151 153
154=item Linux::Clone::pivot_root $new_root, $old_root
155
156Calls pivot_root(2) - refer to its manpage for details.
157
158=item Linux::Clone::kcmp $pid1, $pid2, $type[, $idx1, $idx2]
159
160Calls kcmp(2) - refer to its manpage for details on operations.
161
162The following C<$type> constants are available if the kcmp syscall number
163was available during compilation:
164
165C<Linux::Clone::KCMP_FILE>, C<Linux::Clone::KCMP_VM>, C<Linux::Clone::KCMP_FILES>,
166C<Linux::Clone::KCMP_FS>, C<Linux::Clone::KCMP_SIGHAND>, C<Linux::Clone::KCMP_IO>,
167C<Linux::Clone::KCMP_SYSVSEM> and C<Linux::Clone::KCMP_EPOLL_TFD>.
168
169=item Linux::Clone::configure_loopback
170
171Configures a working loopback interface (basically, does the equivalent of
172"ifconfig lo up" which automatically adds ipv4/ipv6 addresses and routes),
173which can be useful to get a network namespace going.
174
175Dies on error and returns nothing.
176
177=item C<ioctl> symbols
178
179The 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
152=back 186=back
153 187
154=cut 188=cut
155 189
156package Linux::Clone; 190package Linux::Clone;
157 191
158# use common::sense; 192# use common::sense;
159 193
160BEGIN { 194BEGIN {
161 our $VERSION = '1.0'; 195 our $VERSION = '1.3';
162 196
163 require XSLoader; 197 require XSLoader;
164 XSLoader::load (__PACKAGE__, $VERSION); 198 XSLoader::load (__PACKAGE__, $VERSION);
165} 199}
166 200
201sub configure_loopback() {
202 siocsifflags "lo"
203 and die "Linux::Clone::configure_looopback: unable to bring up loopback interface: $!\n";
204}
205
1671; 2061;
207
208=head1 SEE ALSO
209
210L<IO::AIO> has some related functions, such as C<pidfd_send_signal>, and
211some unrelated fucntions that might be useful.
212
213L<cgroup_namespaces(7)>, L<pid_namespaces(7)>, L<user_namespaces(7)>, L<time_namespaces(7)>,
214L<ip-netns(8)>, L<lsns(8)>, L<switch_root(8)>, L<ioctl_ns(2)>.
168 215
169=head1 AUTHOR 216=head1 AUTHOR
170 217
171 Marc Lehmann <schmorp@schmorp.de> 218 Marc Lehmann <schmorp@schmorp.de>
172 http://home.schmorp.de/ 219 http://home.schmorp.de/

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines