1Mojo::IOLoop::ReadWriteUPsreorceCsosn:t:rCiobnuMttoaejidon:eP:reI(rO3lL)oDoopc:u:mReenatdaWtriiotneProcess::Container(3)
2
3
4

NAME

6       Mojo::IOLoop::ReadWriteProcess::Container - (kinda) Pure Perl
7       containers.
8

SYNOPSIS

10           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
11           use Mojo::IOLoop::ReadWriteProcess qw(process);
12
13           my $container = container(
14             pid_isolation => 1,  # Best-effort, as depends on where you run it (you need CAP_SYS_ADMIN)
15             subreaper => 1,
16             group   => "my_org",
17             name    => "my_process",
18             process => process(
19               sub {
20                 # Exec, fork ..
21                 process(sub { warn "\o/"; sleep 42;  })->start;
22                 process(sub { warn "\o/"; sleep 42; })->start;
23                 process(
24                   sub {
25                     process(
26                       sub {
27                         process(sub { warn "\o/"; sleep 42; })->start;
28                         warn "\o/";
29                         sleep 400;
30                         warn "\o/";
31                       })->start;
32                     warn "Hey";
33                     sleep 42;
34                     warn "\o/";
35                   })->start;
36                 sleep 42;
37               }
38             )->separate_err(0));
39
40           $container->start();
41           $container->is_running;
42           $container->stop;
43
44           my @procs = $container->cgroups->first->processes;
45           $container->cgroups->first->pid->max(300);
46
47           $container->process->on(stop => sub { print "Main container process stopped!" });
48

DESCRIPTION

50       Mojo::IOLoop::ReadWriteProcess::Container ties anonymous functions or a
51       Mojo::IOLoop::ReadWriteProcess object to differents sets of
52       Mojo::IOLoop::ReadWriteProcess::CGroup implementations.
53
54       When the "pid_isolation" attribute is set, it needs special permissions
55       (CAP_SYS_ADMIN capabilities).  This module uses features that are only
56       available on Linux, and requires cgroups and capability (CAP_SYS_ADMIN)
57       for unshare syscalls to achieve pid isolation.
58

EVENTS

60       Mojo::IOLoop::ReadWriteProcess inherits all events from
61       Mojo::EventEmitter and can emit the following new ones.
62
63   start
64        $container->on(start => sub {
65          my ($process) = @_;
66           ...
67        });
68
69       Emitted when the container starts.
70
71   stop
72        $container->on(stop => sub {
73          my ($container) = @_;
74          ...
75        });
76
77       Emitted when the container stops.
78
79   process_error
80        $container->on(container_error => sub {
81          my ($e) = @_;
82          my @errors = @{$e};
83        });
84
85       Emitted when the container produce errors.
86

METHODS

88       Mojo::IOLoop::ReadWriteProcess::Container inherits all methods from
89       Mojo::EventEmitter and implements the following new ones.
90
91   start
92           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
93           use Mojo::IOLoop::ReadWriteProcess qw(process);
94
95           my $c = container( name=>"test", process => sub { print "Hello!" });
96           $c->start();
97
98       Starts the container, it's main process is a
99       Mojo::IOLoop::ReadWriteProcess, contained in the "process()" attribute.
100       On stop it will terminate every process included in the cgroups
101       attribute.
102
103   is_running
104           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
105           use Mojo::IOLoop::ReadWriteProcess qw(process);
106
107           my $c = container( name=>"test", process => sub { print "Hello!" });
108           $c->is_running();
109
110       Returns 1 if the container is running.
111
112   stop
113           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
114           use Mojo::IOLoop::ReadWriteProcess qw(process);
115
116           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
117           $c->stop();
118
119       Stops the container and kill all the processes belonging to the cgroup.
120       It also registers all the unknown processes to the current
121       Mojo::IOLoop::ReadWriteProcess::Session.
122
123   wait_stop
124           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
125           use Mojo::IOLoop::ReadWriteProcess qw(process);
126
127           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
128           $c->wait_stop();
129
130       Wait before stopping the container.
131
132   wait
133           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
134           use Mojo::IOLoop::ReadWriteProcess qw(process);
135
136           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
137           $c->wait();
138
139       Wait the container to stop
140
141   migrate_process
142           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
143           use Mojo::IOLoop::ReadWriteProcess qw(process);
144
145           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
146           $c->migrate_process(42);
147
148       Migrate the given process to the container cgroup.
149

ATTRIBUTES

151       Mojo::IOLoop::ReadWriteProcess::Container inherits all attributes from
152       Mojo::EventEmitter and implements the following new ones.
153
154   name
155           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
156           use Mojo::IOLoop::ReadWriteProcess qw(process);
157           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
158           use Mojo::Collection 'c';
159
160           my $container = container( name => "test", process => sub { print "Hello!" } );
161
162           $container->session->on(register => sub { ... });
163           $container->start();
164
165       Sets the container name. It creates in the indicated (or default)
166       cgroups a sub-tree with the container name.
167
168       This means that cgroups settings can be done also outside of the
169       container object:
170
171           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
172           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
173
174           my $container = container( name => "test", process => sub { print "Hello!" } );
175
176           cgroupv1->from($continer->cgroups->first->_group)->pid->max(100);
177
178       As cgroups are represented by path, you can set options directly from
179       controllers objects that are pointing to the same cgroup slice.
180
181   group
182           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
183           use Mojo::IOLoop::ReadWriteProcess qw(process);
184           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv2);
185           use Mojo::Collection 'c';
186
187           my $container = container( name => "bar", group => "foo", process => sub { print "Hello!" } );
188           my $container2 = container( name => "bar2", group => "foo", process => sub { print "Hello!" } );
189
190           $container->start();
191           $container2->start();
192
193           my $group_cgroup = cgroupv2->from($container2->cgroups->first->parent);
194
195           $group_cgroup->pid->max(200);
196
197       Sets the container group. If containers are sharing the same group they
198       will inherit the same CGroup parent path, in such way it is possible to
199       create controllers pointing to it and set specific options for the
200       whole group.
201
202   pid_isolation
203           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
204           use Mojo::IOLoop::ReadWriteProcess qw(process);
205           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
206           use Mojo::Collection 'c';
207
208           my $container = container( pid_isolation => 1, process => sub { print "Hello!" } );
209
210           $container->session->on(register => sub { ... });
211           $container->start();
212
213       If set, the process will see itself as PID 1. It needs CAP_SYS_ADMIN
214       capabilities set on the executable (or run as root).
215
216   pre_migrate
217           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
218           use Mojo::IOLoop::ReadWriteProcess qw(process);
219
220           my $container = container( pre_migrate => 1, process => sub { print "Hello!" } );
221
222           $container->session->on(register => sub { ... });
223           $container->start();
224
225       If set, the process will migrate itself into the cgroup.
226
227   clean_cgroup
228           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
229           use Mojo::IOLoop::ReadWriteProcess qw(process);
230
231           my $container = container( clean_cgroup => 1, process => sub { print "Hello!" });
232
233           $container->session->on(register => sub { ... });
234           $container->start();
235
236       If set, attempts to destroy the cgroup after the process terminated its
237       execution.
238
239   subreaper
240           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
241           use Mojo::IOLoop::ReadWriteProcess qw(process);
242
243           my $c = container(subreaper => 1, name=>"test", process => sub { print "Hello!" });
244           $c->start();
245
246       Enable subreaper mode inside the child process.
247
248   process
249           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
250           use Mojo::IOLoop::ReadWriteProcess qw(process);
251
252           my $c = container(process => sub { print "Hello!" });
253           my $c = container(process => sub { print "Hello!" });
254
255           $c->start();
256
257       The process to run. It can be an anonymous function or a
258       Mojo::IOLoop::ReadWriteProcess object.
259
260   namespace
261           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
262           use Mojo::IOLoop::ReadWriteProcess qw(process);
263
264           my $c = container(process => sub { print "Hello!" });
265           $c->namespace->unshare(0); # All
266           $c->start();
267
268       Set/Return Mojo::IOLoop::ReadWriteProcess::Namespace object. It's main
269       use is to invoke syscalls.
270
271   session
272           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
273           use Mojo::IOLoop::ReadWriteProcess qw(process);
274
275           my $c = container(process => process(sub { print "Hello!" }));
276           $c->session->on(register => sub { ... });
277           $c->start();
278
279       Returns/Set the Mojo::IOLoop::ReadWriteProcess::Session singleton
280       object.
281
282   unshare
283           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
284           use Mojo::IOLoop::ReadWriteProcess qw(process);
285           use Mojo::IOLoop::ReadWriteProcess::Namespace qw( CLONE_NEWPID CLONE_NEWNS );
286
287           my $c = container( unshare=> CLONE_NEWPID | CLONE_NEWNS, process => sub { print "Hello!" } );
288           $c->session->on(register => sub { ... });
289           $c->start();
290
291       Returns/Set the unshare syscall options. See man unshare(2) for further
292       documentation.
293
294   cgroups
295           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
296           use Mojo::IOLoop::ReadWriteProcess qw(process);
297           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
298           use Mojo::Collection 'c';
299
300           my $container = container(process => sub { print "Hello!" });
301           $container->cgroups( c(cgroupv1(controller => 'pids'), cgroupv1(controller => 'memory')) );
302
303           $container->session->on(register => sub { ... });
304           $container->start();
305
306       Returns/Set a Mojo::Collection collection of CGroups where the process
307       should belong to.  If used with a single CGroup, you don't need to pass
308       the Mojo::Collection  object:
309
310           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
311           use Mojo::IOLoop::ReadWriteProcess qw(process);
312           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
313           use Mojo::Collection 'c';
314
315           my $container = container(cgroups=> cgroupv1(controller => 'pids'), process => sub { print "Hello!" });
316
317           $container->session->on(register => sub { ... });
318           $container->start();
319

DEBUGGING

321       You can set the MOJO_EVENTEMITTER_DEBUG environment variable to get
322       some advanced diagnostics information printed to STDERR.
323
324           MOJO_EVENTEMITTER_DEBUG=1
325
326       Also, you can set MOJO_PROCESS_DEBUG environment variable to get
327       diagnostics about the process execution.
328
329           MOJO_PROCESS_DEBUG=1
330

LICENSE

332       Copyright (C) Ettore Di Giacinto.
333
334       This library is free software; you can redistribute it and/or modify it
335       under the same terms as Perl itself.
336

AUTHOR

338       Ettore Di Giacinto <edigiacinto@suse.com>
339
340
341
342perl v5.34.0                      2M0o2j2o-:0:1I-O2L1oop::ReadWriteProcess::Container(3)