-
Notifications
You must be signed in to change notification settings - Fork 24
/
linked-images.txt
1265 lines (947 loc) · 52.6 KB
/
linked-images.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
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
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.. This document is formatted using reStructuredText, which is a Markup
Syntax and Parser Component of Docutils for Python. An html version
of this document can be generated using the following command:
rst2html.py doc/linked-images.txt > doc/linked-images.html
============================
Ips pkg(5) zones integration
============================
:Author: Edward Pilatowicz
:Version: 0.6
.. sectnum::
.. contents::
Introduction
============
To allow for support of pkg(5) within zones and the automatic management
and upgrading of zones during global zone pkg(5) operations, this
proposal describes enhancements to pkg(5) to support "linked images".
The pkg(5) linked images functionality proposed herein is intended to
be generic, with zones being one type of linked images that can be
supported. In addition to supporting zones linked images we also propose
supporting another "system" type of linked images. The details of how
these linked image types differ will be explained in more detail below.
Another goal of the pkg(5) linked image support is to make all the
linked image functionality visible to other pkg(5) subsystems common,
and to isolate code dealing with the different linked image types within
well defined modules contained within the linked image subsystem. IE,
while other pkg(5) subsystems may need to be aware of linked images,
they should not have to worry about specific linked image types.
(zones, system, etc.)
Linked images will have properties associated with them. The set of
available properties may vary across different linked image types. The
storage location for these properties values (IE, linked image metadata)
may be plugin specific. For the "system" plugin, property data
configuration will live within a /var/pkg configuration file. For the
"zones" linked image plugin, property configuration will be derived from
the zones subsystem (some properties will have implicit values, others
may be derived from zonecfg(1m) parameters, etc.)
Zones and linked images
=======================
The design for pkg(5) linked images as proposed herein is primarily
being driven by the need to support zones. Hence, before jumping into
the specifics of linked images support it is worth discussing how zones
user are expected to interact with linked images, and also the
requirements that zones have upon the design of linked images.
Zone users and linked images
----------------------------
Ideally, zone users should be unaware of all linked image functionality
proposed herein. They should never need to run any of the proposed
pkg(1) linked image commands. Linked images will do their work
automatically under the hood when users do operations like:
- Run pkg(1) in the global zone. In this case pkg(1) operations will
automatically keep non-global zones in sync with the global zone.
- Run pkg(1) in a non-global zone. In this case pkg(1) will prevent
operations that would allow a non-global zone to go out of sync with
the global zone.
- Run zoneadm(1m) install/uninstall/detach/attach/etc. In this case the
zone brand callbacks will utilize with the pkg(5) linked image
functionality to manage zones as linked images.
Zones requirements
------------------
Zones is a OS level virtualization technology that allows us to run
multiple userland execution environment on a single kernel. Each of
these userland execution environments is a separate virtual machine,
with it's own filesystem, processes, network stack, etc. The default
execution environment (IE, the one you get when you install Solaris or
OpenSolaris) is called the global zone. Subsequent execution
environments are called non-global zones and can be created and managed
via zonecfg(1M) and zoneadm(1M).
All the zones on a system share the same kernel, and the kernel is
managed by the global zone. Non-global zones can not supply their own
kernel modules. Hence, any software within a zone which spans the
user/kernel boundary must be kept in sync with the kernel installed in
the global zone. This puts constraints on what software can be installed
within zones. The basic requirements here can be summed up as:
- Software installed in a non-global zone that depends on specific
kernel functionality must be kept in sync with the kernel software
installed within the global zone. examples:
libzfs and drv/zfs (system/file-system/zfs)
libdladm (system/library) and drv/dld (system/kernel)
- Software installed in a non-global that communicates to the global
zone via private interfaces must be kept in sync with the kernel
software installed within the global zone. examples:
zones proxy (system/zones)
libdladm (system/library) and dladm (system/network)
- Software that depends on specific kernel functionality can only be
installed in a non-global zone if the corresponding kernel
functionality is installed within the global zone.
Since non-global zones are separate virtual machines with their own
filesystems and software, these machines (and their software contents)
may not be trusted by the global zone. Hence any software management
operations being done on non-global zone should not be able to affect
the global zone. Effectively this means that all actions performed on a
zone cannot safely be done from the global zone environment. This means
that software management operations initiated from a global zone will
either have to "enter" the zone (if it's running) to perform their
operation, or they must take special precautions when accessing zone
images to ensure that all filesystem operations are performed safely.
The basic requirements here can be summed up as:
- Software management operations will need to span multiple processes
operating in different zones.
- Since zones are untrusted execution environment, global zone pkg(5)
operations should not read data from non-global zone. IE, any data
flow required to support linked images must be from a global zone to a
non-global zone, and never in the reverse direction. Also, write
accesses to a non-global zone from the global zone should be kept to
an absolute minimum, and any such accesses must be provably safe via
code inspection.
Lastly, since non-global zones are separate virtual machines, they will
normally not have access to the contents of the global zone. Yet the
software that can be run in non-global zones is constrained by the
software installed in the global zone. Hence:
- All the constraints required to perform software management operations
within a non-global zone must be persistently available within that
zones image/filesystem.
Zones non-requirements
----------------------
While developing linked images, existing Solaris 10 zones users have
asked how linked images will enable them to continue to do certain zones
administrative operations that they are familiar with. Unfortunately,
some of these operations were possible mainly as side effects of the
zones and SVR4 packaging implementations on Solaris 10. Since pkg(5) is
significantly changing the way zones are used and managed, some of these
legacy operations will no longer be possible and users will need to
adopt new ways of managing their zones. So here are some of the
requests from Solaris 10 users that we're not initially addressing with
linked images.
**The ability to install a patch on all zones on a system.**
Patching of systems with pkg(5) will be substantially different from the
patching of Solaris 10 system. This change is the administrative model
is being driven by pkg(5) and is largely orthogonal to zones. With
pkg(5), patching of systems will be done via pkg(1) update, where
repositories are populated with the latests versions of packages that
all system should be running, and when systems are updated they
will automatically install the latest versions of software available
within the repositories they are using. Hence, if an administrator
wants to install updated packages onto a system with zones, they should
push the updated packages into their repositories and update their
zones.
**The ability to install a package on all zones on a system.**
Previously in Solaris 10, the package content of zones closely tracked
the package content of the global zone. In most cases installing a
package in the global zone would result in that package being installed
in all zones. With pkg(5) the contents of zones are much more decoupled
from the contents of global zones. We will not be providing a way to
install packages across multiple zones. In general, system should only
contain the software that they need for their operation. Hence, this
software should be installed at zone installation time. Or if added
later, it needs to be added directly into the zone image (via a pkg(1)
install run within that zone image).
We may subsequently create new mechanisms to help with operations like
the ones above. Such mechanisms might take the form of recursive
operation support, a simple image content policy mechanism, or some
larger system life cycle management mechanism that defines the package
software content of systems for their entire deployment (instead of just
at install time).
Possible linked image types
===========================
So in addition to supporting zones linked image, the design herein has
also considered other future possible types of linked images. So before
going into the details of the linked image design it's worth while to
first describe some possible linked image types to understand when and
where they might be used.
**Zones linked images**
Support for zones linked images is included in this proposal. Users
will not be able to directly create or manage zones linked images.
Instead the system will automatically manage zones linked images when
zones are used. Zones linked images should provide us with with a
means to do the following:
- Allow for the creation of non-global zone images where the contents
of those images is constrained by the software installed in the
global zone.
- Allow for the updating of software within non-global zones while
taking into account the constraints placed upon the zone by the
software installed in the global zone.
- Allow pkg(5) operations initiated from (and operating on) the global
zone to update non-global zone images as required to keep them in
sync with software being updated in the global zone.
- Allow for pkg(5) operations initiated directly upon non-global zone
image to take into account the constraints placed upon then by the
software installed in the global zone.
- Allow for the auditing of non-global zones to verify that their
software contents are in sync with the software installed in the
global zone.
**System linked images**
Support for system linked images is included in this proposal. These
types of linked images will be very similar to zone linked images. All
the features listed above that will be available for zones linked
images will also be available for system linked images. But unlike
zone linked images, these images can be created via new pkg(1)
interfaces.
Support for system linked images is included in this proposal because
it is anticipated that system linked images will be used internally
within Solaris. Also, having a "system" linked image type will
greatly facilitate the testing of linked image functionality, the
large majority of which is common to all linked image types.
**User linked images**
Support for user linked images is NOT included in this proposal. These
type of images would be managed very differently from zones or system
linked images. User linked images could provide us with the following
functionality:
- Allow for arbitrary users to create user linked images, where the
contents of that image are in sync with the software installed in
another image.
- Allow for a user to update the software within a user linked image
while staying in sync with the software installed in another image.
- Allow for the auditing of a user linked image to verify that their
software contents are in sync with the software installed in another
image.
So here's an example of how a user linked image might work. Say a user
named Ed wants to run a copy of SpamAssassin on a system named
jurassic, but jurassic doesn't have SpamAssassin installed. Ed could
then create a "user" linked image that is linked to the jurassic
system image. Then he could install SpamAssassin into that image.
Pkg(5) would install a version of SpamAssassin that is compatible with
the software contents already installed on jurassic. (In the process
of doing this pkg(5) would also install into the user image any
dependencies required by SpamAssassin that were missing from
jurassic.) Ed could then run this version of SpamAssassin without
having to worry about his software being out of sync with the system.
The system administrator would have no knowledge of user images that
might be created on a system, hence, if the administrator updates the
software on a system then any user images may now be out of sync. In
this case, Ed would be able to perform an audit of all his user linked
images to determine if they are in sync with their specified policy
and the contents of the system they are being used on. If they were
out of sync (due to the system being updated) he could then initiate a
sync operation to update them and bring them back in sync.
**Diskless client linked images**
Support for diskless client linked images is NOT included in this
proposal. These types of images would probably not be managed
directly, but would probably be managed indirectly by diskless client
management tools. One possible deployment model for diskless clients
would be to create a parent image which represents the standard
diskless client configuration deployment, and then to create linked
images all parented to that one parent image. These linked images
would actually be the diskless client root filesystems. Subsequent
software management operations could be performed on the parent image,
with changes automatically propagated to all the client images
automatically based on the content policy of the linked images.
**Distributed linked images**
Support for Distributed linked images is NOT included in this
proposal. But if pkg(5) functionality was accessible over the network
via rad interfaces, it should be possible to create linked image
relationships that span multiple machines. This could be used in a
manager similar to diskless clients where a master deployment image is
created on one machine, and this master image is then linked to
machines which deploy the image. Subsequently, updates to the master
image would automatically be propagated to deployment machines, based
of the content management policy being used.
Out of scope
============
There are many components which will probably be required to allow
pkg(5) and zones to work seamlessly together. This proposal does not
address all of them. Specifically, the following features are not being
delivered by this project.
**User, diskless, and distributed linked images.**
While this project will provide basic support for creating system and
zone linked images, it will not provide support for any other types of
linked linked images, even though other types of linked images may be
discussed within this document.
**Offline zone install.** [1]_
This proposal does nothing to address the current requirement that an
active network connection to a valid package repository be available
during most pkg(5) operations. If anything, this proposal will
increase the number of operations that may require such a connection
to be available.
**The system repository.** [2]_
When managing zone linked images, it's critical that certain packages
be kept in sync between global and non-global zones. This means that
zones must have access to any publishers that contain packages that
must be kept in sync between the images, regardless of the zones
publisher configuration. Some additional complications to this problem
are that for zones which are not running, we may not be able to
instantiate their network configuration, so we may not be able to talk
to any of their configured network based publishers. The planned
solution to address these problems is to create "system repository".
The system repository would allow a linked image to access any
publishers configured within the parent image that contain packages
which needed to be kept in sync with the child image.
Since delivery of the system repository is out of scope for this
project, initially zones linked image support will rely on zones
having a publisher configuration which provides access to all the
packages required to keep the zone in sync.
**Zones image locking.** [3]_
When performing pkg(5) operations in a global zone that affect the
contents of the global zone, we need a locking mechanism to prevent
concurrent operations from being done within a non-global zone. We
also need a locking mechanism that allows for the reverse. Ie, if a
zone is in the middle of a pkg(5) operation we don't want to initiate
an operation from the global zone which might also require updating
that zone. Other scenarios that we will probably also need to protect
against include a zone changing state while we're performing a pkg(5)
operation on that zone. For example, if we're installing a package in
a global zone which results in us also installing a package in a
non-global zone, we need to prevent that non-global zone from
rebooting while we're installing the package. Another example is that
if we're installing or removing a package from a global zone, we will
probably want to prevent a concurrent install of a non-global zone
since that could results in the freshly installed zone being out of
sync with the global zone. This proposal does not address any of the
possible race conditions wrt pkg(5) and zone linked image operations.
**Pkg(5)/beadm(1M) image filesystem management.** [4]_
Currently, beadm(1M) allows for versioning (via snapshotting and
cloning) of multiple filesystem in a global zone image, assuming all
those filesystems are zfs based and are all children of the current
root filesystem. beadm(1M) treats any other filesystems in the current
BE as shared and lofs mounts them into any other alternate BE. This
means that if any pkg(5) software is installed into these "shared"
filesystems that software will become out of sync wrt some BE. Pkg(5)
and beadm(1M) do not perform any check to ensure that all the software
being installed is not being installed into "shared" filesystems. This
same problem also affects zones. This proposal does not address this
issue in any way and assumes that eventually pkg(5) or beadm(1M) will
provide more flexible and robust functionality to manage images that
span multiple filesystem.
**Beadm(1M) support for linked images.**
Currently, beadm(1M) can be run within the global zone to manage
global zone boot environments and their associated zones. But
beadm(1M) does not support running within a non-global zone and
creating snapshots of zone boot environments from within a zone.
Beadm(1M) support within a zone is a requirements for supporting
pkg(5) update within a zone. (Since update only operates
on alternate boot environments.) It is also the case that other pkg(5)
operations may refuse to operate on the currently running image and
may only be run on cloned and offline boot environments. Since
beadm(1M) can not be run within a zone, we can't create cloned boot
environments within a zone, so none of these operations will be
supported.
Additionally, beadm(1M) is currently aware of zones images, but
eventually, beadm(1m) should probably become linked image aware, since
all linked images should be snapshotted, cloned, and upgraded in sync.
Enhancing beadm(1M) will be required to support non-zone types of
linked images that live outside the current boot environment. Once
this project delivers initial pkg(5) linked image interfaces it will
be possible to update beadm(1M) to consume these interfaces so that it
can be aware of all linked images on the system, instead of just zone
images. These beadm(1M) enhancements are out of the scope of this
proposal.
pkg(5) linked image overview
============================
pkg(5) linked images will always always have a parent and child
relationship. Parent images may have multiple children, but each child
image may only have one parent. It's possible for there to be multiple
levels of linked images (i.e., nested linked image), for example, you
could have a system linked image, which is a child of a zone linked
image, which is the child of a global zone image.
pkg(5) linked image name
------------------------
All pkg(5) linked images are uniquely identified by a name. A fully
qualified linked image name is <linked image type>:<linked image name>.
The linked image name must begin with an alphanumeric character and can
contain alphanumeric characters, underscores (_), hyphens (-), and dots
(.). Additional restrictions on the <linked image name> format may be
defined by the linked image plugin handling that type of linked image.
pkg(5) linked image attach mode
-------------------------------
As previously mentioned, all linked images will have a parent/child
relationship. But there are two distinct ways that this parent/child
link can be established, which in turn determines what operations are
possible on each image and how the linked image relationship is managed.
First, a parent may link/attach a child image to itself, in which case,
the parent image will be authoritative for the linked image
relationship. This means that:
- The parent image is aware of the child image.
- The child image will know that it is a linked image, but it will
not know the location of it's parent image.
- Linked image properties can only be modified from the parent image and
are treated as read-only within the child image.
- Packaging operations on the parent image which require updating child
images to keep them in sync will attempt to do so automatically.
Second, an image may make itself into a child by linking/attaching
itself to a parent. In this case the parent has no awareness of the
child image and the child image is authoritative for and must manage the
linked image relationship. This means that:
- The parent image is unaware of the child image.
- The child image will know that it is a linked image, and it will
know the location of the parent image.
- Linked image properties only exist within (and there for must be
modified from within) the child image.
- Packaging operations on the parent image will not directly affect the
child image. It is the responsibility of the child image to make sure
that it remains in sync with it's parent.
In the former image linking mode, the parent must "push" constraint (and
property) information to child images. While in the latter mode the
child will "pull" constraint information from the parent.
Zones linked images will exclusively use the push linking mode.
System linked images will support both the push and pull linking modes.
pkg(5) linked image properties
------------------------------
As mentioned earlier, each child linked image will have properties
associated with it.
In the case of both push and pull based child images, linked image
property information will always be stored within a private file and
directory in the pkg(5) image metadata directory. Currently either
/.org.opensolaris,pkg/linked/ or /var/pkg/linked/.
In the case of push based parent images, the property information for
child images is accessible through a plugin for managing each different
type of linked image. This allows each linked image type to manage the
storage of linked image properties. In the case of system linked
images, child linked image properties will be stored within the image
configuration. In the case of Zones linked images, linked image
properties may either be fixed or derived from different zonecfg(1m)
options.
Initially the following properties will be supported:
**li-name**
This is a linked image name (as described above).
This property is common to all linked image types, both push and
pull based.
Notably, this property always refers to a child linked image and
never a parent image. This is because the linked image name encodes
what type of linked image the child is.
**li-mode**
This indicates the attach mode of the linked image child (as
described above), either push or pull.
This property is common to all linked image types, both push and
pull based.
**li-path**
This is the filesystem path by which one linked image is accessible
from another.
In the case of a parent image with a push based child, this property
will point to the child image. From within the push based child,
this property will not be present. In the case of pull based
children, this property will point to the parent linked image.
**li-recurse**
This property specifies if recursive linked image operations should
continue to recurse within a linked child.
This property only exists for push based children of a parent image.
By default, for zones this property will be set to false. This means
that if we do an recursive pkg(5) operation in the global zone that
affects a non-global zone, we will update that non-global zone, but we
will ignore any children of that non-global zone. So if for example,
a non-global zone administrator has created a push based child of the
non-global zone image, global zone pkg operations will not recurse
into that child image.
pkg(5) linked image interfaces
==============================
pkg(1) linked image interfaces introduction
-------------------------------------------
Linked image support has an impact on the behavior and interfaces of
many pkg(5) operations. Hence, before jumping into all the new linked
image interfaces it makes sense to discuss some of the common linked
image behaviors and options to pkg(1) cli interfaces.
pkg(5) operation recursion
~~~~~~~~~~~~~~~~~~~~~~~~~~
Any pkg(1) subcommand which installs or removes packages from a linked
image may attempt to recurse into linked child images to attempt to
keep those child images in sync with the parent. There are two things
to note about this recursive behavior.
First, the initial recursion into child images by a pkg(5) operation
on a parent image has no relation to the li-recure linked image
property. This property is only used when dealing with multiple
levels of recursion. If this property is false for a child image, a
recursive operation will still descend into that child, but it will
not continue to recursively descended into children of that child.
Second, it's important to realize that recursion doesn't imply that
the operation being performed on the parent will also be performed on
all it's children. Recursion into children is only done to keep child
images in sync. To clarify this point it's worth explicitly
describing how this impacts common pkg(5) operations.
**pkg(1) install** - When an install recurses into child linked images,
it does so only to keep those images in sync. Hence, if a user
installs a new package in a parent image, the requested package will
not automatically be installed into child images. Although if a
user "upgrades" a package in the parent image by installing a newer
version of that package, and that package also happens to be kept in
sync between the parent and child images, then the recursive sync
done as part of the install operation will result in the newer
package being installed in the child image.
**pkg(1) update** - This is handled similarly to a pkg(1) install.
When we recurse into the child we do not do a pkg(1) update. We
will only update the minimum number of packages required to keep the
child in sync with the planned contents of the parent image.
**pkg(1) uninstall** - When an uninstall recurses into a child, it will
not uninstall the specified packages within that child. Hence if a
random un-synced package is removed from a parent image it will not
be touched in a child image. But if the user tries to remove
a synced package which is installed within a child image, the
removal will fail. The user will have to remove the package from
child images before they can remove it from the parent image.
pkg(1) linked image common cli options: ignoring children
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As mention above, any pkg(1) subcommand which installs or removes
packages from a linked image may attempt to recurse into linked child
images to attempt to keep those child images in sync with the parent.
There for, these pkg(1) commands will all get new options to allow
them to ignore linked child images. These pkg(1) commands include::
attach-linked [-I | -i <li-name>]
change-facet [-I | -i <li-name>]
change-variant [-I | -i <li-name>]
update [-I | -i <li-name>]
install [-I | -i <li-name>]
set-property-linked [-I | -i <li-name>]
sync-linked [-I | -i <li-name>]
uninstall [-I | -i <li-name>]
Note that the list of commands above does not include pkg(1) commands
like verify, fix, and change-facet, since those commands will never
result in packages being installed or removed from an image.
Unintuitively, set-property-linked is included in the list above since
it may be used to change linked image properties which may results in
in packaging contents changes in that image, which in turn may need to
be propagated to linked children.
When performing one of the above operations, the operation is first
planned in the parent image, and if there are required packaging
changes then we will recurse to each child image and create a plan to
keep each child in sync with the planned changes in the parent. If a
plan which keeps a child image in sync cannot be created then the
operation will fail before any image is modified. In this case, if
the administrator wants to retry the requested operation they will
need to do one of the following before that operation will succeed:
- Detach the child image preventing the operation.
- Modify the package contents of the child image that is preventing
the operation such that the operation can succeed.
- Pass the -i <li-name> option to the requested pkg(1) command,
there by telling it to ignore the specified child image that is
preventing the operation.
- Use the -I option to requested pkg(1) command, there by telling
it to ignore all child images.
Notably, in certain cases it's possible for a push based child linked
image to exist but not be accessible from the parent. An example of
this would be when a non-root user runs a pkg(1) command, all zone
linked image paths will not be accessible. If pkg(1) is attempting to
do any operation which may recurse into child images, all children
must be accessible and if any child is not accessible the operations
will fail and no updates will be made to any image.
pkg(1) linked image common cli options: selecting children
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some of the proposed linked image pkg(1) commands support common
arguments that allow the caller to specify which linked image they
should operate on. These new commands and options are::
property-linked [-l <li-name>]
set-property-linked [-l <li-name>]
audit-linked [-a|-l <li-name>]
detach-linked [-a|-l <li-name>]
sync-linked [-a|-l <li-name>]
If one the above commands is run without any arguments, then the
command will be preformed on the current image with the assumption
that the current image is a linked child image. If the current image
is not a child image an error will be generated.
If the "-l <li-name>" option is specified to one of the commands
above, then it's assumed that the current image has a child by that
name and the requested operation is run for that child.
If the "-a" option is specified to one of the commands above, then the
command is run for all the children of the current image.
pkg(1) linked image common cli options: syncing parent metadata
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a child image is linked to a parent in pull mode, then certain
pkg(1) subcommands will always attempt to update linked image metadata
from their parent. This update will fail if the parent image is not
accessible. Hence, a new --no-parent-sync option is available for to
skip this parent metadata sync. The pkg(1) commands which support
this option are:
attach [--no-parent-sync]
audit [--no-parent-sync]
change-facet [--no-parent-sync]
change-variant [--no-parent-sync]
update [--no-parent-sync]
install [--no-parent-sync]
list [--no-parent-sync]
sync [--no-parent-sync]
pkg(1) linked image cli interfaces
----------------------------------
pkg(1) list-linked
~~~~~~~~~~~~~~~~~~
**pkg list-linked [-H]**
List all known child images associated with the current image. This
lists the name and path for each child image.
Here's an example of this command when run by a non-root user on a
system with zones::
$ pkg list-linked
NAME RELATIONSHIP PATH
- self /
zone:dhcp child /export/zones/dhcp/root
zone:z1 child /export/zones/z1/root
zone:z3 child /export/zones/z3/root
system:child child /child
pkg(1) property-linked
~~~~~~~~~~~~~~~~~~~~~~
**pkg property-linked [-H] [-l <li-name>] [propname ...]**
List all property values associated with a linked image. If no linked
image is specified then if the current image is assumed to be a child
linked image and it's properties are listed.
Here's an example of this command when run on an image that is not
linked::
$ pkg -R /tmp/a list-linked
$
Here's an example of this command when run on an image that has
children but is not itself a child::
$ pkg property-linked
PROPERTY VALUE
li-altroot /
li-path /
Here's an example of this command when run by a non-root user on a
system with zones::
$ pkg property-linked -l zone:dhcp
PROPERTY VALUE
li-altroot /
li-model push
li-name zone:dhcp
li-path /export/zones/dhcp/root
Here's an example of this command when run by a root user directly on
a zone/child image::
# pkg -R /export/zones/dhcp/root property-linked
PROPERTY VALUE
li-altroot /export/zones/dhcp/root
li-model push
li-name zone:dhcp
li-path /export/zones/dhcp/root/
pkg(1) audit-linked
~~~~~~~~~~~~~~~~~~~
**pkg audit-linked [--no-parent-sync] [-a|-l <name>]**
Audit the package contents of a linked image to see if it's in sync
with the contents of it's parent image and it's content policy.
Here's an example of this command when run on an image that has no
parent::
$ pkg audit-linked
pkg: Linked image exception(s):
Current image is not a linked child: /
Here's an example of this command run by root on a system with zones::
# pkg audit-linked -a
NAME STATUS
zone:dhcp diverged
zone:z1 diverged
zone:z3 diverged
system:child synced
pkg(1) sync-linked
~~~~~~~~~~~~~~~~~~
| **pkg sync-linked [-a|-l <name>]**
| **[--no-parent-sync] [--no-pkg-updates] [--linked-md-only]**
| **[-nvq] [--accept] [--licenses] [--no-index] [--no-refresh]**
Sync will attempt to bring an image into sync with it's policy.
A sync operation may upgrade packages or install new packages into an
image while bringing the image into sync. If the user wants to
prevent a sync from installing new packages or updating existing
packages, they can specify the --no-pkg-updates option. If the image
cannot be synced without installing or updating packages, then this
option will cause the sync operation to fail.
If the caller doesn't want to make any packaging updates to the child
image then they can specify the --linked-md-only option. (This option
implies the --no-pkg-updates option.) When this option is specified
the package contents of an image will not be modified, and the only
result of the operation is that the parent content data stored within
the child image will be updated.
Since a sync operation may modify the packaging contents of an image
it is very similar to a pkg(1) install operation, there for the sync
command also must support of the same options as the pkg(1) install
command. Those common options are::
[-nvq] [--accept] [--licenses] [--no-index] [--no-refresh]
Here's an example of this command when run on an image that has no
parent::
$ pkg sync-linked
pkg: detach-linked failed (linked image exception(s)):
Current image is not a linked child: /
Here's an example of this command run by root on a system with zones::
# pkg sync-linked -l zone:dhcp -v
Solver: [ Variables: 2356 Clauses: 60384 Iterations: 2 State: Succeeded]
...
Maintained incorporations: None
Package version changes:
...
pkg://opensolaris.org/[email protected],5.11-0.125:20091014T044127Z -> pkg://opensolaris.org/[email protected],5.11-0.139:20100511T142142Z
...
pkg(1) set-property-linked
~~~~~~~~~~~~~~~~~~~~~~~~~~
| **pkg set-property-linked [-l <name>]**
| **[--no-parent-sync] [--no-pkg-updates] [--linked-md-only]**
| **[-nvq] [--accept] [--licenses] [--no-index] [--no-refresh]**
| **<propname> <propvalue>**
This command will attempt to update the specified linked image
property.
Certain linked image properties may be read-only, and which properties
are read-only may vary between different types of linked images. When
dealing with push based child images, all linked image properties are
treated as read-only within the child.
Since a set-property-linked operation can change a linked image's
content policy, this command may need to sync a child image with it's
parent. Hence, the set-property-linked command also supports many of
the same options as the pkg(1) sync-link command. Those common
options are::
[--no-parent-sync] [--no-pkg-updates] [--linked-md-only]
[-nvq] [--accept] [--licenses] [--no-index] [--no-refresh]
pkg(1) attach-linked
~~~~~~~~~~~~~~~~~~~~
| **pkg attach-linked (-c|-p)**
| **[--no-pkg-updates] [--linked-md-only]**
| **[-nvq] [--accept] [--licenses] [--no-index] [--no-refresh]**
| **[--prop-linked <propname>=<propvalue> ...]**
| **<li-name> <dir>**
The attach-linked command is used to establish a linked image
relationship. This command may not be supported for all linked image
types. (For example, zone linked images cannot be attached via this
command.)
If a parent image want to link a child image to itself, the -c option
should be specified. This creates a child with a push mode of
operation. If a child image wants to attach to a parent image, the -p
option should be specified. This creates a child with a pull mode of
operation.
When linking images the user may specify optional linked image
property values. Not all properties are settable via these values.
(The allowable properties may change in the future and may also be
linked image type plugin specific.)
Normally when linking images together, a sync of the child image is
automatically done. If the child image can not be synced the attach
will fail. Since an attach operation tries to sync a child image with
it's parent, the attach-linked command must also support many of the
same options as the pkg(1) sync-link command. Those common options
are::
[--no-pkg-updates] [--linked-md-only]
[-nvq] [--accept] [--licenses] [--no-index] [--no-refresh]
Currently, linked image relationships cannot be created at image
creation time. A linked image relationship can only be established at
between two existing images. The reason for this is mainly cli
complexity. Specifically, supporting this would require that pkg(1)
image-create accept all the same commands options as the pkg(1)
attach-linked command.
Here's an example of this command attaching a push child image::
# pkg -R attach-linked -v -c system:child /child
Create boot environment: No
Rebuild boot archive: No
Services:
None
pkg(1) detach-linked
~~~~~~~~~~~~~~~~~~~~
**pkg detach-linked [-a|-l <li-name>]**
The detach-linked command will end a linked image relationship. This
command may not be supported for all linked image types. (For
example, zone linked images cannot be detached via this command.)
Here's an example of this command when run on an image that is not
linked::
# pkg detach-linked
pkg: detach-linked failed (linked image exception(s)):
Current image is not a linked child: /
Here's an example of this command when run directly on a child that
linked to a parent via a push mode relationship::
# pkg -R /child detach-linked
pkg: detach-linked failed (linked image exception(s)):
Parent linked to child, can not detach child: /child
Here's an example of this command detaching a child image::
# pkg detach-linked -l system:b -v
Create boot environment: No
Rebuild boot archive: No
Services:
None
pkg(5) linked image manifest metadata
-------------------------------------
When dealing with zones, package publishers need a way to specify which
packages must be kept in sync between zone images. In Solaris 10 this
was done via a SVR4 packaging attribute (SUNW_PKG_ALLZONES). With
pkg(5) we will create a new manifest depend actions for this
purpose::
depend type=parent
If a package contains this dependency and it is being installed into an
image which is not a linked child then this dependency is ignored. If a
package containing this image is being installed into a child image,
then it's required that the same package be installed within the parent
image. This dependency has an implicit fmri value which is equal to the
package fmri which contains the dependency. Also, when matching fmris
in the parent image, the fmri version matching algorithm employed is the
same as that used for satisfying "incorporate" dependencies. (Ie, an
exact version match is required, not a equal than or greater version
match.)