File: o-saft-docker

package info (click to toggle)
o-saft 19.01.19-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 6,764 kB
  • sloc: perl: 18,248; tcl: 2,857; sh: 2,089; makefile: 1,956; awk: 274; ruby: 75; xml: 38; php: 8
file content (628 lines) | stat: -rwxr-xr-x 23,738 bytes parent folder | download
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
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
#!/bin/sh
#?
#? NAME
#?       $0 - wrapper script to handle O-Saft in a Docker image
#?
#? SYNOPSIS
#?       $0
#?       $0 build
#?       $0 usage
#?       $0 shell
#?       $0 root
#?       $0 status
#?       $0 inspect
#?       $0 rmi
#?       $0 apk  package
#?       $0 apt  package
#?       $0 gui
#?       $0 sshx
#?       $0 call /path/to/program [arguments]
#?       $0 cp   file-to-be-copied
#?       $0 [options and commands of o-saft.pl]
#?
#? OPTIONS
#?       -help   got it
#?       -n      do not execute, just show what would be done
#?       -v      be a bit verbose
#?       -id=ID  use Docker image ID (registry:tag); default: owasp/o-saft
#?       -tag=23 use Docker image ID with tag; default: (empty)
#?       -OSAFT_VERSION=21.11.12  same as OSAFT_VERSION environment variable
#?       --      pass all remaining parameters to o-saft.pl in Docker image
#?
#? QUICKSTART
#?       The main purpose of this wrapper is to provide a very simple call of
#?       o-saft.pl  in a running O-Saft Docker image. It is the default mode.
#?       Example:
#?           $0 +info your.tld
#?
#? DESCRIPTION
#?       This is a multipurpose wrapper to handle O-Saft in a Docker image.
#?       It can operate in following modes:
#?           build   - build the Docker image for O-Saft from Dockerfile
#?           usage   - print the initial usage message for O-Saft in Docker
#?           status  - show various information about O-Saft Docker image
#?           rmi     - remove O-Saft Docker image(s)
#?           apk     - add and commit packages in O-Saft Docker image
#?           shell   - run a shell (/bin/sh) in Docker image
#?           root    - run a shell (/bin/sh) as user root in Docker image
#?           call    - run specified program with arguments in Docker image
#?           cp      - copy file to /O-Saft directory in the Docker image
#            hacker  - show more information
#?           gui     - start o-saft.tcl in the Docker image (display to host)
#?           sshx    - start o-saft.tcl in the Docker image (tunnel X via ssh)
#?           *       - anything else (default): run o-saft.pl in Docker image
#?
#?       This wrapper expects, that the O-Saft Docker image has the name:
#?           owasp/o-saft
#?       If there are more Docker images with the same (registry) name, a tag
#?       can be used to identify the image, see  -tag=TAG  option, i.e.
#?           $0 -tag=17.07.17 +info your.tld
#?       will use the name:  owasp/o-saft:17.07.17 .  The  -id=ID  option can
#?       be used to redefine the (registry:tag) name to be used completely.
#?       For example:
#?           owasp/o-saft:4711
#?
#?       If any other mode than the default is used, please see  WARNING  and
#?       SECURITY  below.
#?
#? TERMINOLOGY
#?
#?   Docker vs. docker
#?       The term "Docker" is used when the Docker system in general is meant.
#?       The term "docker" is used when the Docker client program is meant.
#?
#?   mode vs. command
#?       The term "mode" is used for our script, which is similar to the term
#?       "command" of Docker. This is to distinguish the commands herein from
#?       those of Docker.
#?
#?   "o-saft.pl in Docker image"
#?       Means that the program defined by O-Saft Docker's ENTRYPOINT will be
#?       executed. This can be  o-saft.pl  or  o-saft .
#?
#? MODES
#?       Modes are simply an alias  to call  docker  with the proper commands
#?       and options for the  O-Saft Docker image. Most modes use the command
#?       "docker run --rm ...".
#?       This wrapper ensures that the proper O-Saft image within Docker will
#?       be used by passing the correct  "repository:tag"  image id (default:
#?       owasp/o-saft). This script will exit, if the image owasp/o-saft does
#?       exist (to avoid automatic pull from Docker's repository).
#?
#?       The modes are:
#?
#?   default
#?       In default mode,  all parameters given to this wrapper are passed to
#?       o-saft.pl  in the Docker image. This means that for all the existing
#?       calls, the name of the script (usually o-saft.pl) needs simply to be
#?       replaced by  $0 . Example:
#?           o-saft.pl +info your.tld
#?       becomes
#?           $0 +info your.tld
#?       Please see  LIMITATIONS  below also.
#?
#?   gui
#?       Start  o-saft.tcl in the Docker image with display to the host where
#?       started.
#?
#?   sshx
#?       Start  o-saft.tcl in the Docker image using ssh  to tunnel X  to the
#?       hosts display.
#?
#?   build
#?       This mode builds the Docker image for O-Saft from the Dockerfile. If
#?       ./Dockerfile is missing following will be used:
#?           https://github.com/OWASP/O-Saft/raw/master/Dockerfile
#?       See  ENVIONMENT VARIABLES below for supported environment variables.
#?
#?   apk
#?   apt
#?       Add and commit the specified packages in O-Saft Docker image.
#?       Note that this creates a new layer for the O-Saft Docker image.
#?       For more advanced mode, please refer to  o-saft-docker-dev.
#?       Uses  apk or apt  to add/install the package, depending on the mode.
#?
#?   rmi
#?       Remove all O-Saft images, including tagged images.
#?
#?   usage
#?       Print a brief purpose and usage of this script.
#?       It is intended to be called from within the Docker image once, right
#?       after the initial build (see Dockerfile).
#?
#?   shell
#?       Start a shell in O-Saft Docker image.
#?       This is useful because the  ENTRYPOINT  in the image is  o-saft  or
#?       o-saft.pl , which otherwise will always be executed.
#?
#?   root
#?       Same as mode  shell, but login as user root.
#?
#?   cp
#?       Copy file to /O-Saft directory in the Docker image.
#?
#?   call
#?       Execute specified program with given arguments.  The program must be
#?       found using $PATH or a full path.
#?       This might be usefull to retrieve other information  from the image,
#?       i.e. O-Saft  itself uses it to get the environment variables set in 
#?       the image:
#?           $0 call /usr/bin/env
#?
#?   inspect
#?       Print information about O-Saft Docker image using inspect command.
#?
#?   status
#?       Show various information about O-Saft Docker image.
#?
#? WARNING
#?       It is highly recommended to  *not* use the created image as base for
#?       other Docker images. Also,  do *not*  use openssl from the image for
#?       other purpose than O-Saft intends.
#?
#? SECURITY
#?       When working with Docker images, at least two types of security have
#?       to be observed.
#?
#?       It is rather difficult to create a secure Docker image, at least the
#?       pulled files (Dockerfile, image, other sources) must be trusted.
#?
#?       The known security types are:
#?
#?   Security of the created images
#?       When creating Docker images, wether using  build, load or pull,  you
#?       must trust the sources: the binary (load or pull) or the  Dockerfile
#?       (which may be fetched at runtime too) used to build the image.
#?
#?       Update June/2018: Crypto-Miner in Docker images detected:
#?           https://www.fortinet.com/blog/threat-research/yet-another-crypto-mining-botnet.html
#?           https://kromtech.com/blog/security-center/cryptojacking-invades-cloud-how-modern-containerization-trend-is-exploited-by-attackers
#?           https://sysdig.com/blog/detecting-cryptojacking/
#?       That's why we prefer a transparent build of the Docker image. We re-
#?       comment to build the Docker image for O-Saft using the Dockerfile.
#?
#?   Security of the tools executed from within the image (docker run)
#?       If the image is trustworthy (see before),  the tools executed in the
#?       image may have security impacts. 
#?       This script creates a Docker image for O-Saft. O-Saft is supposed to
#?       checks a target for SSL/TLS related issues.  I. g. it doesn not harm
#?       the target using  penetration or attacking techniques  (except check
#?       for Heartbleed vulnerability). So o-saft.pl itself should not be any
#?       security issue. However, to perform the checks, O-Saft recommends to
#?       install a special version of OpenSSL. This OpenSSL has functionality
#?       enabled, which is known to be insecure (i. e. SSLv2, SSLv3).
#?
#?       That's why this script uses a transparent method to create an image.
#?       
#? HACKER's INFO
#?       Options for this script are with a single - (dash) only, because the
#?       same options with double  --  exist for  o-saft.pl. See  LIMITATIONS
#?       below also.
#
#        We do not use shortcut commands for docker like run, rmi, save, etc.
#        because they are depricated according docker documentation.
#
#        Keep in mind that docker is picky about the sequence of commands and
#        options. In particular all options must preced the IMAGE argument.
#
#        "docker commit ..." is used without the --message option because the
#        documentation about  --message and/or -m  is ambigious.  Also passed
#        comment text is mainly the same as Docker already reports with the
#        "docker history IMAGE"  command in the  "CREATED BY" column.
#
# KNOWN PROBLEMS
#        * Error when building docker image
#            fetch http://dl-cdn.alpinelinux.org/alpine/edge/main/x86_64/APKINDEX.tar.gz
#            WARNING: Ignoring http://dl-cdn.alpinelinux.org/alpine/edge/main/x86_64/APKINDEX.tar.gz: temporary error (try again later)
#            fetch http://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz
#            WARNING: Ignoring http://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz: temporary error (try again later)
#            ERROR: unsatisfiable constraints:
#
#          Reason: backend mirror  dl-cdn.alpinelinux.org  down or not responding
#          Most likely an update of the host's docker package will fix it.
#?
#? LIMITATIONS
#?       The options  -n  -v  -id=ID  and  -help  must be specified  leftmost
#?       if they should apply for this script.
#?       These options can only be passed to  o-saft.pl  in the Docker image,
#?       if they are preceeded by the  --  parameter.
#?       Unknown parameters to this script will be treated as arguments to be
#?       passed to o-saft.pl and will terminate internal argument scanning in
#?       this script.
#?       The script calls the program defined by the ENTRYPOINT in the Docker
#?       image (which is most likely o-saft).
#?       This script is not intended to call  o-saft.cgi in the Docker image.
#?       However, it is possible to do so:
#?           $0 call o-saft.cgi --cgi [options and commands of o-saft.pl]
#?
#? ENVIONMENT VARIABLES
#?       Following environment variables can be used to pass settings to the
#?       script:
#?
#?           OSAFT_VERSION          - version to be passed to Dockerfile
#?           OSAFT_VM_SRC_OSAFT     - URL to o-saft.tgz
#?           OSAFT_VM_SRC_SSLEAY    - URL to Net-SSLeay.tgz
#?           OSAFT_VM_SRC_SOCKET    - URL to IO-Socket.tgz
#?           OSAFT_VM_SRC_OPENSSL   - URL to openssl.tgz
#?           OSAFT_VM_SHA_OSAFT     - checksum of o-saft.tgz
#?           o_saft_docker_name     - contains an image registry name
#?           o_saft_docker_tag      - contains an image tag
#?
#?       To get the build-in defaults use:
#?           $0 status
#?
#? EXAMPLES
#?       See  SYNOPSIS.
#?
#? SEE ALSO
#?       docker(1), o-saft-docker-dev, o-saft.pl, o-saft.tcl
#?
#? VERSION
#?       @(#) o-saft-docker 1.41 18/11/09 01:14:13
#?
#? AUTHOR
#?      17-jul-17 Achim Hoffmann
#?
# -----------------------------------------------------------------------------

VERSION="${OSAFT_VERSION:-18.11.18}"
tag=${o_saft_docker_tag};     # tag=${tag:-17.09.17}
registry=${o_saft_docker_name}; registry=${registry:-owasp/o-saft}
image_name="${registry}"
entrypoint_pl='ENTRYPOINT ["perl", "/O-Saft/o-saft.pl"]';   # default ENTRYPOINT
entrypoint_sh='ENTRYPOINT ["/O-Saft/o-saft"]';              # default ENTRYPOINT
entry__cmd='CMD ["--norc", "--help=docker"]':               # default CMD
[ -n "$tag" ] && image_name="${registry}:${tag}"
try=
exe=o-saft.pl
dockerfile="https://github.com/OWASP/O-Saft/raw/master/Dockerfile"

check_image_name () {
	#? check if image with configured registry:tag exists; exit otherwise
	# This function should be called before most docker commands.
	# This tool does not allow automatic pull by default.
	# Most (all?) Docker commands automatically try to pull the specified
	# image if it does not exist.  More worse, while some Docker commands
	# use any matching registry name  (run without --entrypoint=), others
	# require that the registry:tag name exists (run with --entrypoint=).
	# Unfortunately Docker  does not provide  any option or configuration
	# to inhibit such automatic pulls.
	# This function tries to find existing images matching the configured
	# image (name). The function exits the script if the found image name
	# does not equal the configured image name.
	# Lists all images matching the required one. As "docker image ls -q"
	# reports the image IDs only, duplicate image IDs may be returned.
	# Images which are just tags, return the same image ID.  Hence we can
	# simply filter them using "sort -u".
	#dbx#  \docker image ls ${image_name} -q | \sort -u | \wc -w
	is_id=`\docker image ls ${image_name} -q | \sort -u | \wc -w`
	[ "${is_id}" -eq 1 ] && return; # found image, return

	[ "${is_id}" -ne 1 ] && \
		echo "**ERROR: given image '${image_name}' does not match found image(s)" # '${is_id}'"
	if [ "${is_id}" -gt 1 ]; then
		for tag in `\docker image ls ${image_name} | \awk '/^REPOSITORY/{next}{print $2}'` ; do
			# varaiable tag is the same as the global one!
			echo "#        consider using  option -id=${image_name}:$tag  or  -tag=$tag"
		done
	fi
	exit 3;     # no image found, exit script
}

docker_usage () {
	_me=${0##*/}
	# TODO: env|grep osaft_vm_build
	_openssl="/openssl/bin/openssl";      # TODO: still hardcoded for docker
	if [ -n "$osaft_vm_build" ]; then
		_openssl="openssl"            # we're inside docker
		_me=${0##*/}
	else
		_openssl="$0 call $_openssl"  # we're outside docker
		_me=$0
	fi
	_ciphers=`$_openssl ciphers -V ALL:COMPLEMENTOFALL:aNULL | \wc -l`
	cat << EoDescription

      # openssl:
	$_openssl supports $_ciphers ciphers 

      # o-saft.pl:
	O-Saft docker image is ready to run o-saft.pl, use:

		docker run --rm -it ${image_name} +info your.tld
	or:
		$me +info your.tld
	or:
		o-saft -docker +info your.tld

      # o-saft.tcl:
	The GUI  o-saft.tcl  will only work inside Docker if the packages tcl
	tk and xvfb are installed. However  o-saft.tcl  may be started on the
        host and then use  o-saft.pl  from the Docker image.

	# run on host:

		o-saft.tcl --docker

	# run in Docker image

		$0 apk tcl tk xvfb
		$0 gui
		$0 gui your.tld

EoDescription
}
# TODO: alpine:3.8 misses 'tablelist' there seems to be no package 'tklib'

docker_hacker () {
	cat << EoHacker

	To use the GUI  o-saft.tcl  inside Docker, additionl packages need to
	be installed. For Docker image based on alpine, following works:

		$0 apk add tcl tk xvfb

EoHacker
}

docker_inspect () {
	$try \docker image inspect ${image_name}
}

docker_status () {
 	image_id=`\docker image ls -q ${image_name}`
	cat << EoStatus
# using environment ...
#     OSAFT_VERSION      = $OSAFT_VERSION
#     o_saft_docker_name = $o_saft_docker_name
#     o_saft_docker_tag  = $o_saft_docker_tag

# using ...
#     registry name = ${registry}
#     tag           = ${tag}
#?    registry:tag  = ${image_name}

# docker image id for ${image_name} is  $image_id

# docker images for   ${registry} ...
EoStatus

	# list matching images
	$try \docker image ls ${registry}; # will be listed below again
	# list related (tagged) images
	for _id in  `\docker image ls -q ${registry}` ; do
		$try \docker image ls | \grep "$_id"
	done;
	echo
	echo "# docker processes ..."
	$try \docker container ls -a

	echo ""
	echo "# O-Saft docker image ..."
	_id=`$0 call env | grep osaft_vm_build`
	if [ -n "$_id" ]; then
		echo "$_id"
	else
		echo "<<no build variable 'osaft_vm_build' found>>"
	fi
}

docker_build () {
	# build O-Saft Docker image from Dockerfile, mainly using defaults
	# from Dockerfile; cleanup the containers
	_arg1=
	_arg2=
	_arg3=
	_arg4=
	_arg5=
	_tar=./o-saft_docker.tar
	_cfg=./Dockerfile
	[ ! -e $_cfg ] && $try \wget ${dockerfile} -O $_cfg
	# pass environment variables (known by Dockerfile) to docker build
	[ -z "$OSAFT_VERSION" ]        && OSAFT_VERSION="$VERSION"  # use hardcoded VERSION if environment missing
	[ -n "$OSAFT_VERSION" ]        && _arg0="--build-arg OSAFT_VERSION=$OSAFT_VERSION"
	[ -n "$OSAFT_VM_SRC_OSAFT"   ] && _arg1="--build-arg OSAFT_VM_SRC_OSAFT=$OSAFT_VM_SRC_OSAFT"
	[ -n "$OSAFT_VM_SRC_SSLEAY"  ] && _arg2="--build-arg OSAFT_VM_SRC_SSLEAY=$OSAFT_VM_SRC_SSLEAY"
	[ -n "$OSAFT_VM_SRC_SOCKET"  ] && _arg3="--build-arg OSAFT_VM_SRC_SOCKET=$OSAFT_VM_SRC_SOCKET"
	[ -n "$OSAFT_VM_SRC_OPENSSL" ] && _arg4="--build-arg OSAFT_VM_SRC_OPENSSL=$OSAFT_VM_SRC_OPENSSL"
	[ -n "$OSAFT_VM_SHA_OSAFT"   ] && _arg5="--build-arg OSAFT_VM_SHA_OSAFT=$OSAFT_VM_SHA_OSAFT"
	# TODO: do we need more of these variables?
	$try \docker image build -f ./Dockerfile --force-rm --rm -t ${image_name} \
		$_arg0 $_arg1 $_arg2 $_arg3 $_arg4 $_arg5 .	&& \
	$try \docker image save  -o $_tar ${image_name}	&& \
	$try \docker image rm    `$try docker image ls -q ${image_name}` && \
	$try \docker image load  -i $_tar && \
	$try \rm                    $_tar && \
	$try \docker image tag   ${image_name} o-saft	&& \
	$try \docker image tag   ${image_name} ${image_name}:$OSAFT_VERSION
}

docker_osaft () {
	# this is the command for the default mode, passing all parameters
	# expects a proper ENTRYPOINT like /O-Saft/o-saft.pl in the image
	$try \docker container run --rm -i  ${image_name} $@
}

docker_gui   () {
        # start GUI in docker with display to host
	# --entrypoint= not really necessary if ENTRYPOINT=/O-Saft/o-saft
	$try \docker container run --rm -i  --entrypoint=/O-Saft/o-saft.tcl \
		-e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix ${image_name} $@
}

docker_sshx  () {
	_ssh=`\docker port ${image_name} 22`
	if [ -z "${_ssh}" ]; then
		echo "**ERROR: no ssh port available for '${image_name}'"
	else
		# use "ip addr" to get docker's ip, should return something like:
		#   6: docker0    inet 172.17.0.1/16 brd 172.17.255.255 scope global ...
		# TODO: returns IP of last interface if more than on exists
		_ip=`\ip -4 -o addr | \awk '($2~/docker/){sub("/..","",$4);print $4}'`
		$try \ssh user@${_id} -p ${_ssh} /O-Saft/o-saft.tcl
	fi
}

docker_call ()  {
	cmd="$1"
	shift
	$try \docker container run --rm -it --entrypoint=$cmd    ${image_name} $@
}

docker_shell () {
	$try \docker container run --rm -it --entrypoint=/bin/sh ${image_name}
}

docker_root ()  {
	$try \docker container run --rm -it --entrypoint=/bin/sh --user root ${image_name}
}

docker_cp   ()  {
	_id="o-saft-cp"
	# create a new container with a dummy command; exit if exists or fails
	$try \docker container run   --name ${_id} ${image_name} +VERSION || exit 4
	$try \docker container cp    $@     ${_id}:/O-Saft/
	$try \docker container commit       ${_id} ${image_name}
	$try \docker container rm           ${_id}
	#
	# if we need to reset the entrypoint:
	# $try \docker container commit       \
	#	--change='ENTRYPOINT ["perl","/O-Saft/o-saft.pl"]' \
	# or:
	# $try \docker container commit       \
	#	--change='ENTRYPOINT ["/O-Saft/o-saft"]' \
	#
}

docker_apk  ()  {
	_id="o-saft-apk"
	# after commit the entrypoint is changed, hence the original one is
	# set again with commit's --change option; unfortunately hardcoded
	$try \docker container run -t --user root --entrypoint=/sbin/apk \
				--name      ${_id} ${image_name} add --no-cache $@ \
		|| exit 4
	$try \docker container commit \
		--change="${entrypoint_sh}" --change="${entry__cmd}" \
					    ${_id} ${image_name}
	$try \docker container rm           ${_id} 
	return

	# TODO: following more cleaner method does not work (reason yet unknown)
	$try \docker container run  -d --name ${_id} ${image_name} +VERSION || exit 4
	$try \docker container exec -t --user root ${_id} /sbin/apk add --no-cache $@
	$try \docker container commit       ${_id} ${image_name}
	$try \docker container rm           ${_id} 
}

docker_apt  ()  {
	_id="o-saft-apt"
	$try \docker container run -t --user root --entrypoint=/usr/bin/apk \
				--name      ${_id} ${image_name} install --no-cache $@ \
		|| exit 4
	$try \docker container commit \
		--change="${entrypoint_sh}" --change="${entry__cmd}" \
					    ${_id} ${image_name}
	$try \docker container rm           ${_id} 
}

docker_rmi  ()  {
	# parameters can only be the options for Docker's rmi command
	#dbx# echo "# registry: ${registry} # image_name: ${image_name}"
	_ids=`\docker image ls -q ${registry}` # ${image_name}
	echo "# image IDs to be deleted: $_ids "
	# need to find all images,  including referenced images, this is done
	# with "images" command, then extract all lines with matching IDs,
	# only these IDs are deleted
	# Note: "docker images"  should return newest image on top, hence all
	#       images which just represent a tag (alias) come first and will
	#       be deleted first
	\docker image ls | while read _any ; do
		for _id in $_ids ; do
			_img=`echo "$_any" | \awk "/$_id/"'{print $3}'`
			#dbx# echo "# ID  $_any : $_id : $_img"
			[ -z "$_img" ] && continue  # other image
			$try \docker image rm -f $@ $_img
		done
	done
	$try \docker image rm ${registry}
}

my_help ()      {
	ich=${0##*/}
	\sed -ne "s/\$0/$ich/g" -e '/^#?/s/#?//p' $0
}

# first check for options
while [ $# -gt 0 ]; do
	case "$1" in
	  '-n')     try=echo; ;;
	  '-v')     set -x  ; ;;
	  -tag=*)   tag="`expr "$1" ':' '-tag=\(.*\)'`"
	            image_name="${registry}:$tag" 
	            ;;
	  -id=*)    image_name="`expr "$1" ':' '-id=\(.*\)'`"; ;;
	  -OSAFT_VERSION=*)     OSAFT_VERSION="`expr "$1" ':' '-OSAFT_VERSION=\(.*\)'`"; ;;
	  '-help')  my_help;    exit 0; ;;
	  *)        break;  ;;
	esac
	shift
done

# don't run inside docker
case "$1" in
  'hacker') ;;
  'usage')  ;;
  *)        if [ -n "$osaft_vm_build" ]; then
		echo "**ERROR: cannot run inside docker image; exit"
		exit 1
	    fi
	    ;;
esac

# some modes do not need to check existing images
case "$1" in
  'build')  ;;
  'usage')  ;;
  'hacker') ;;
  *)        check_image_name;   # may exit, see description there
esac

# NOTE: All functions may use ${registry} and ${image_name}, which are global
#       variables. We do not pass these values as parameters to the functions
#       because we want $@ (all parameters of this script) in the functions
while [ $# -gt 0 ]; do
	mode="$1"
	shift
	case "$mode" in
	  'build')  docker_build;   exit 0; ;;
	  'usage')  docker_usage;   exit 0; ;;
	  'call')   docker_call $@; exit 0; ;;
	  'sshx')   docker_sshx $@; exit 0; ;;
	  'gui')    docker_gui  $@; exit 0; ;;
	  'cp')     docker_cp   $@; exit 0; ;;
	  'apk')    docker_apk  $@; exit 0; ;;
	  'rmi')    docker_rmi  $@; exit 0; ;;
	  'root')   docker_root;    exit 0; ;;
	  'shell')  docker_shell;   exit 0; ;;
	  'inspect')docker_inspect; exit 0; ;;
	  'status') docker_status;  exit 0; ;;
	  'hacker') docker_hacker;  exit 0; ;;
#          -registry=*) registry=  # not supported, as this is for O-Saft only
          '--')     shift; break; ;;
          *)               break; ;;
	esac
done
set -- "$mode" $@ ; # 1st argument has no special meaning, pass to o-saft.pl

if [ $# -lt 1 ]; then
	# did not get any argument, print own usage
	my_help
	echo
	echo "**WARNING:  $0  called without parameters; nothing done."
	echo
	exit 2
fi

docker_osaft $@

exit