-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathREADME.txt
399 lines (296 loc) · 11.9 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
==================================================
Kains — container tool based on Linux namespaces
==================================================
Synopsis
========
kains [options] ... [command]
Description
===========
Kains's main purpose is to confine programs within a virtual rootfs.
However it is possible to selectively make files of the actual rootfs
visible from the virtual rootfs. Kains can also be used to make files
and directories accessible elsewhere in the file-system hierarchy.
Kains does not need any privileges or setup, although it requires
Perl 6 runtime and a Linux kernel that supports user namespaces.
Options
=======
The command-line interface is composed of two parts: first Kains's
parameters, then the command to launch (the default is "/bin/sh -l" if
none is specified). This section describes the parameters supported
by Kains, that is, the first part of its command-line interface:
-r $path
--rootfs $path
Use $path as the new root file-system, aka. virtual rootfs.
Programs will be executed from, and confined within the virtual
rootfs specified by $path. Although, files and directories of the
actual rootfs can be made visible from the virtual rootfs by using
"-b" and "-B". By default the virtual rootfs is "/", this makes
sense when using "-B" to relocate files within the actual rootfs,
or when using "-0" to fake root privileges.
It is recommended to use "-R" or "-S" instead.
Some examples:
-r ~/rootfs/centos-6-x86
-r /tmp/ubuntu-12.04-x86_64
-r / (default)
-b $path
-m $path
--bind $path
--mount $path
Make $path visible from the virtual rootfs, at the same location.
The content of $path will be made visible from the virtual rootfs.
Unlike with "-B", the location isn't changed, that is, it will be
accessible as $path within the virtual rootfs too.
Some examples:
-b /proc
-b /dev
-b $HOME
-B $path $location
-M $path $location
--bind-elsewhere $path $location
--mount-elsewhere $path $location
Make $path visible from the virtual rootfs, at the given $location.
The content of $path will be made visible at the given $location
from the virtual rootfs. This is especially useful when using "/"
as the virtual rootfs to make the content of $path accessible
somewhere else in the file-system hierarchy.
Some examples:
-B ~/my_hosts /etc/hosts
-B /tmp/opt /opt
-B /bin/bash /bin/sh
-w $path
--pwd $path
--cwd $path
--working-directory $path
Set the initial working directory to $path.
Some programs expect to be launched from a specific directory but
they do not move to it by themselves. This option avoids the need
for running a shell only to change the current working directory.
Some examples:
-w /tmp
-w $PWD (first default)
-w / (second default)
-0
--root-id
Set user and group identities virtually to "root/root".
Some programs will refuse to work if they are not run with "root"
privileges, even if there is no strong reasons for that. This is
typically the case with package managers. This option changes the
user and group identities to "root/root" in order to bypass this
kind of limitation, however all operations are still performed
with the original user and group identities.
--32
--32bit
--32bit-mode
Make Linux declare itself and behave as a 32-bit kernel.
Some programs launched within a 32-bit virtual rootfs might get
confused if they detect they are run by a 64-bit kernel. This
option makes Linux declare itself and behave as a 32-bit kernel.
-R $path
Use $path as virtual rootfs + bind some files/directories.
Programs will be executed from, and confined within the virtual
rootfs specified by $path. Although a set of files and
directories of the actual rootfs will still be visible from the
virtual rootfs. These files and directories contain information
that are likely required by virtual programs:
- /etc/host.conf
- /etc/hosts
- /etc/hosts.equiv
- /etc/mtab
- /etc/netgroup
- /etc/networks
- /etc/passwd
- /etc/group
- /etc/nsswitch.conf
- /etc/resolv.conf
- /etc/localtime
- /dev/
- /sys/
- /proc/
- /tmp/
- /run/
- $HOME
-S $path
Use $path as virtual rootfs + bind some files/directories + fake "root".
This option is similar to "-0 -R" but it makes visible from the
virtual rootfs a smaller set of files and directories of the
actual rootfs (to avoid unexpected changes):
- /etc/host.conf
- /etc/hosts
- /etc/nsswitch.conf
- /etc/resolv.conf
- /dev/
- /sys/
- /proc/
- /tmp/
- /run/shm
- $HOME
This option is useful to create and install packages into the virtual
rootfs.
-h
--help
--usage
Print the help message, then exit.
-- @command
Launch @command in the virtual environment.
This option is only syntactic sugar since it is possible to
specify the @command at the very end of the command-line,
ie. after all other options.
Some examples:
-- emacs
-- /usr/bin/wget
-- /bin/sh -l (default)
Exit Status
===========
If an internal error occurs, Kains returns a non-zero exit status,
otherwise it returns the exit status of the last terminated program.
When an error occurs, the only way to know if it comes from the
confined program or from Kains itself is to have a look at the error
message.
Tutorial
========
In this tutorial, it is assumed "~/rootfs/ubuntu-12.04/" contains
files from an Ubuntu 12.04 system. See section "Download" to obtain
such a rootfs easily.
To confine a program using Kains, specify the path to the virtual
rootfs using the "-r" option, followed by the program name and its
arguments. For instance, the command below executes "cat /etc/motd"
confined into "~/rootfs/ubuntu-12.04":
$ kains -r ~/rootfs/ubuntu-12.04/ cat /etc/motd
Welcome to Ubuntu 12.04.5 LTS
Kains executes "/bin/sh -l" if no program is specified, thus the
shortest way to confine an interactive shell is:
$ kains -r ~/rootfs/ubuntu-12.04/
Once a program is confined, all its sub-programs are confined too.
For example, when executing "cat /etc/motd" from the interactive shell
above:
$ cat /etc/motd
Welcome to Ubuntu 12.04.5 LTS
Although, some programs needs to access files of the actual rootfs.
For instance:
$ kains -r ~/rootfs/ubuntu-12.04/
$ ps -o tty,command
Cannot find /proc/version - is /proc mounted?
The solution is to tell Kains to make these files visible from the
virtual rootfs, using the "-b" option:
$ kains -r ~/rootfs/ubuntu-12.04/ -b /proc
$ ps -o tty,command
TT COMMAND
? [...]
? /bin/sh -l
? ps -o tty,command
? -bash
Actually there's a bunch of such required files, that's why Kains
provides an option that both confines and makes a predefined set of
files visible from the virtual rootfs:
$ kains -R ~/rootfs/ubuntu-12.04/
$ ps -o tty,command
TT COMMAND
pts/0 [...]
pts/0 /bin/sh -l
pts/0 ps -o tty,command
pts/0 -bash
It is possible that some programs will not work correctly if they are
not run by the "root" user, this is typically the case with package
managers. In this case, Kains will fake the root identity and its
privileges if the "-0" (zero) option is specified:
$ kains -r ~/rootfs/ubuntu-12.04/ -0
# id
uid=0(root) gid=0(root) [...]
# mkdir /tmp/foo
# chmod a-rwx /tmp/foo
# echo 'I bypass file-system permissions.' > /tmp/foo/bar
# cat /tmp/foo/bar
I bypass file-system permissions.
This option is typically required to create or install packages into
the virtual rootfs. However, it is not recommended to use the "-R"
option when installing a package since it may try to update files of
the host rootfs that were made visible from the virtual rootfs, like
"/etc/group" for instance. Instead, it is highly recommended to use
the "-S" option. This latter enables the "-0" option and make visible
a smaller set of files that are known to not be updated by packages:
$ kains -S ~/rootfs/ubuntu-12.04/
# apt-get install build-essential
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following extra packages will be installed:
[...]
It is worth saying that the default path to virtual rootfs is "/" if
none is specified. In this case, Kains is typically used to make
files accessible somewhere else in the actual rootfs. This is useful
to trick programs that perform access to hard-coded locations, like
some installation scripts:
$ kains -B /tmp/alternate_opt /opt
$ cd to/sources
$ make install
[...]
install -m 755 prog "/opt/bin"
[...] # prog is installed in "/tmp/alternate_opt/bin" actually
As shown in the example above, it is possible to override files or
directories not even owned by the user. This can be used to change
the system configuration temporally and locally, ie. without impacting
programs not executed by Kains. For instance, with the DNS setting:
$ ls -l /etc/hosts
-rw-r--r-- 1 root root 675 Mar 4 2011 /etc/hosts
$ touch ~/alternate_hosts
$ kains -B ~/alternate_hosts /etc/hosts
$ echo '1.2.3.4 google.com' > /etc/hosts
$ resolveip google.com
IP address of google.com is 1.2.3.4
$ echo '5.6.7.8 google.com' > /etc/hosts
$ resolveip google.com
IP address of google.com is 5.6.7.8
Another example: on most Linux distributions "/bin/sh" is a symbolic
link to "/bin/bash", whereas it points to "/bin/dash" on Debian and
Ubuntu. As a consequence a "#!/bin/sh" script tested with Bash might
not work with Dash. In this case, Kains can be used to set
non-disruptively "/bin/bash" as the default "/bin/sh":
$ kains -B /bin/bash /bin/sh [...]
Installation
============
Kains is written in Perl 6. The easiest way to get a Perl 6 runtime
is to use rakudobrew:
$ git clone https://github.com/tadzik/rakudobrew ~/.rakudobrew
[...]
$ export PATH=~/.rakudobrew/bin:$PATH
$ rakudobrew build moar
[...]
Then, Kains can be used that way:
$ git clone https://github.com/cedric-vincent/kains
$ cd kains
$ make
[...]
$ perl6 -Ilib ./bin/kains
[...]
Rootfs
======
Here follows a couple of URLs where some archived rootfs can be freely
downloaded. Note that "mknod" errors reported by "tar" when
extracting these archives should be ignored since special files of the
actual rootfs can be made visible from the virtual rootfs (see "-R"
option for details).
- http://download.openvz.org/template/precreated/
- https://images.linuxcontainers.org/images/
- http://distfiles.gentoo.org/releases/
- http://cdimage.ubuntu.com/ubuntu-core/releases/
- http://archlinuxarm.org/developers/downloads
Technically such archived rootfs can be created by running the
following command on the expected Linux distribution:
tar --one-file-system --create --gzip --file my_rootfs.tar.gz /
License
=======
The following copyright notice both applies to this file and to Kains
sources:
Copyright (C) 2015 STMicroelectronics
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.